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Preface 



This manual gives you conceptual information 
about using the 5110 with the APL language. 
Before using this manual, you should understand 
the information in the IBM 5110 APL Introduction, 
SA21-9301, especially: 

• How to enter data from the keyboard 

• How APL functions work with one or two 
arguments 

• How to create your own user-defined functions 
using the built-in APL functions 

This manual is intended to be used with the IBM 
5110 APL Reference Manual, SA21-9303; that is, 
this manual gives you information about using the 
5110 system with the APL language for 
information processing. The major topics are: 

• Computer concepts for data processsing 
(Chapter 1 ) 

• An approach to breaking your application into 
small parts to make programming easier 
(Chapter 2) 

• Elements of the APL language and example APL 
user-defined functions used for information 
processing (Chapter 3) 

• Controlling the information in the active 
workspace (Chapter 4) 

• Using uppercase and lowercase characters, 
scrolling the display screen up or down, and 
sounding the audible alarm (Chapter 5) 

• Creating, using, and maintaining your library 
(Chapter 6) 

• Using the tape or diskette storage media 
(Chapters 7 and 8) 



• Formatting printed reports and example 
user-defined functions used for formatting 
reports (Chapter 9) 

• Creating and using data files for your business 
applications (Chapter 10) 

• Determining what to do when your program 
doesn't work (Chapter 11) 

This manual is not intended to give you a 
complete description of the syntax and rules 
required for each APL command, function, or 
variable; you must use the 57 70 APL Reference 
Manual for this information. 

This manual does not need to be read chapter by 
chapter. Instead, you can read the appropriate 
chapters as required. For example, you might read 
Chapter 9, Printer Control when you need to 
format a report. 

This manual follows the convention that he means 
he or she. 



Prerequisite Publication 

IBM 5110 APL Introduction, SA21-9301 

Related Publications 

IBM 5110 APL Reference Manual. SA2 1-9303 

IBM 5110 APL Reference Card. GX2 1-9304 

IBM 5110 Customer Support Functions Reference 
Manual, SA21-9311 
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Chapter 1. Data Processing Concepts 



INTRODUCTION 

The IBM 5110 Models 1 and 2 are multipurpose data processing 
systems with a personal touch. Because of their compact size and 
large-scale capabilities, these systems provide solutions to problems 
for a wide variety of users. As a 5110 user, only you can determine 
the problems to be solved with your system. To help you make these 
determinations, this chapter contains general concepts of data 
processing. You may or may not choose to read this chapter, 
depending on your data processing knowledge and experience. 



CONCEPTS 

What can you expect a computer to do with information? How do you 
get information into a computer? How does a computer know what to 
do with your information? What final results can you expect from a 
computer? This section gives general answers to these questions. 

Today the computer is doing many jobs, from accounting to predicting 
election results to guiding spaceships. It is often looked upon as some 
kind of magical machine, but the computer performs no magic. 
Everything a computer does is dependent on the people who use it 
and the instructions they supply. For every job you want a computer 
to do, you must give a step-by-step procedure (a program) for it to 
follow. This procedure is then stored inside the computer. The 
information you want is processed according to the stored 
instructions. 

A computer can do only a few rather simple things, but it does them 
extremely well. It can retrieve, almost instantly, any item of 
information stored in it. It can compare any two items of information, 
and do any arithmetic operations you want: add, subtract, multiply, or 
divide. It can be instructed to do any combination of these things in 
any sequence you want them done. 

The computer works methodically, doing one thing at a time. When it 
finishes one step, it goes on to the next, then the next, and the next, 
according to instructions. But it performs these steps at an almost 
unbelievable speed until it comes up with the answer you want. 
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The task performed by a computer is called data processing. Data 
processing means that information is handled according to a set of 
rules. Whether you process information by hand or use a computer, 
the requirements of a job remain about the same. You must have 
input, which is the data you want to do something with; you must 
process the data, which is the act of doing something with data 
according to instructions; and you must have output, which is the 
result of your processing. 

To help you understand the 5110 and data processing, let's first look 
at how a clerk might process information for the job of billing. For this 
job, assume the clerk works with the following data: 

« Customer orders 

» Price catalogs 

» Customer records 

9 Accounts receivable records 

• Inventory files 




The clerk receives a copy of the customer orders after orders are 
shipped. He uses these documents to prepare bills that he sends to 
customers. To prepare the bill, he follows this procedure: 

1 . Look up, in a price catalog, the price of each item on the order. 

2. Multiply the price by the quantity shipped. 

3. Add the total price of items to get the total amount of bill. 

4. Check the customer records to see if any special discounts apply, 
and adjust the bills accordingly. 

5. Type the bill. 

6. Adjust the accounts-receivable records to show what the 
customer owes. 

7. Update the inventory records to show the reduced stock. 

For each billing, the clerk follows the same procedure. In computer 
terms, this procedure is his program for doing the job. The customer 
order is his input, the calculating and file updating he does is 
processing, and the results of the processing (the billing and updated 
records) are his output. 

The 5110 can speed up the billing operation and reduce costly errors. 
The order information can be entered from the keyboard; the records 
(such as price lists, customer records, accounts receivable records, 
and inventory files) can be quickly referenced and updated (processed) 
using tape or diskette storage; and the printer can print the billings. 

The parts of the 5110 used for data processing are; 

Input 

• The keyboard from which data is entered into the system. 

• Tape or diskette storage from which data can be read for 
processing. 

Processing 

• The 5110 internal storage, which includes the active workspace. The 
active workspace is where calculations are performed and where 
user-defined functions (programs) and variables are stored. 
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Output 

• The display screen, which displays keyboard input and the results of 
executed expressions br statements. That is, the display screen is a 
means of communication between the system and you. 

• The printer, which prints keyboard input (if specified) and the results 
of executed expressions or statements. This printed output is 
sometimes called hard copy output. 

• The tape or diskette on which data can be stored for future 
processing. 




As mentioned before, a program is a procedure or set of instructions 
you establish for doing a job. These instructions are necessary 
because a computer cannot think for itself. When defining a program 
for the 5110, you can use a programming language called APL APL is 
a simple-to-use programming language with which you describe how 
you want the 5110 to do a job. Also, in APL, a program is called a 
user-defined function. 



The next chapter presents an approach to analyzing a problem or job 
so that an APL user-defined function can be used to help process 
information. 



Chapter 2. Infoimation Processing 



This chapter presents an approach to dissecting an application so that 
APL user-defined functions can be used to help process the 
information. This approach helps you break down the application into 
manageable parts so that you can apply APL expressions and 
commands to process the information. Breaking the application down 
into manageable parts promotes thoroughness and allows the 
application to be solved (programmed) faster. 



INPUT, PROCESS, AND OUTPUT 

Every application consists of three parts: 

• The input required for processing. 

• The process (APL expressions) required to generate the final result 

• The output, which is the final result 

Each part might consist of one or more APL expressions. In the 
following sections, each part is discussed in more detail. Also, an 
example for finding the compound interest is used to illustrate each 
part. 
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Output 



Because the output or result is the primary reason for a user-defined 
function to exist, considering the output provides the best place to 
start solving a problem. To do this, consider these questions: 

1 . What results are required? 

2. How should the results be formatted? 

3. Who uses the results? For example, should the results be 
displayed or printed, or should the results be stored in the active 
workspace, on tape, or on diskette for later use? 

Now, for the compound interest example, assume the answers to 
these questions are: 

1 . The amount of interest earned. 

2. The message THE INTEREST EARNED IS: followed by the 
calculated interest earned. 

3. Finance officers will use the displayed results to evaluate 
different plans. 

Once you have answered these questions, you know the purpose of a 
user-defined function. 



Input 



After the output, you should consider what input data is required to 
generate the output. To do this, consider such questions as: 

1. What input is required? 

2. Where does the input come from? 

3. How is the input provided? 

Continuing with the compound interest example, the answers to these 
questions are: 

1 . The interest rate, number of years, and principal. 

2. From finance officers who need to know the amount of interest 
earned for different plans. 

3. Through the 5110 keyboard. 

In our example, most of the input data will come from the keyboard; 
however, other ways also exist. For example, some data might be 
permanent and be included within the user-defined function (for 
example, headings and labels). There might also be data that is usually 
constant but, for certain problems, must be changed. This data might 
be coded in the user-defined functions as variables that can be 
modified. And, of course, data might also be from tape or diskette. 

The following list summarizes the input and output considerations so 
far: 



Data Device 



Input 



Output 



I merest rate Keyboard 

Number of years 

Principal 

THE INTEREST EARNED IS: Display Screen 
The calculated Interest earned 
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Process 

Your introduction to APL started with APL's processing ability. The 
APL language is designed to do processing with a minimum number of 
instructions. 

Once the input and output are well defined, all of the characteristics 
work together to make the process part the most straightforward. 

For our compound interest example, the process part consists of: 

1 . Defining the algorithm used to calculate the compound interest 

2. Using the input to generate the results 

The formula used in this example for the compound interest is: 

CI = Principal x (1 + .01 x Interest Rate)y«"^ 

The APL statements that use the input to generate the results might 
be as follows: 

a<-:l+.oi><:i:nterestrate 

B<-Aw YEARS 
CfPRINCIPALxB 

PUTTING IT ALL TOGETHER 

Now that you have considered the three parts of the application, it is 
time to write your user-defined function. For the compound interest 
example, your user-defined function might look like this: 

The Interest rate must be 
V 55'-':'' Jf^" ''^h,?,'J^e?'i!^?, -^'^SS^assigned to this variable before 
r -■ - ml , vrv" p " ' "' the user-defined function is 

i: 3 1 c :i: <• ? r :i: nc :i: pal. m b executed. 

\:M1 Rf'THE INTEREST EARNED IS: ' , :l.0 2 tCI 

V 

So far, you have taken a simple application and designed a 
user-defined function to solve it. If the application is larger or more 
complex, a more detailed structure is required. This more detailed 
structure involves expanding each of the three parts (input, process, 
and output) into additional levels of input, process, and output. 



ADDITIONAL LEVELS OF INPUT, PROCESS, AND OUTPUT 



User-Defined 
Function 



INPUT 



Input 



PROCESS 



OUTPUT 



First Level 



Process 



A 



Output 



Additional Levels 



The method shown in the previous diagrann breaks the first-level 
INPUT, part into manageable parts. Let's continue with the compound 
interest problem and treat the INPUT portion as a separate problem in 
Itself. 

First, consider the output of the INPUT portion. Here the output is 
actually the input for the first-level PROCESS portion. In this case, 
assume that the output must be an interest rate not greater than 18%, 
a number of years not greater than 40, and a principal not greater than 
500000.00. 

Next, consider the input for the INPUT portion. The input is the same 
as before (the interest rate, number of years, and principal for which 
the interest earned must be calculated). However, in this case, the 
finance officers might be unfamiliar with the user-defined function; 
therefore, there should be prompting messages telling them what to 
enter. 

Finally, consider the process for the INPUT portion. In this case, the 
processing consists of jerror checking and validation of all the input 
data, because you want to make sure that the interest rate is not 
greater than 18%, the number of years is not greater than 40, and the 
principal is not greater than 500000.00 
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Now, taking these considerations into account, the APL statennents for 
the first-level input portion might be: 



? l-JfEXAMPLE . . 

i:i:j start: 'entizr the interest rate, years, and prxncipai 

L-2:i Xi-U 

i::3::i ■■> < ( xi: i ::i > le ) , ( xi:2:3 >»m) > , < xi::3::i >50 o o o o > ) /ei , E2 , E3 

i::m:i •* process 

151 El: 'THE interest RATE IS GREATER THAN IS PERCENT' 

i:6:j "^start 

1:7:3 e2:'the number of years is greater than »+0 ' 

r:B:i -^start 

[:93 E3:"THE PRINCIPAL IS GREATER THAN 500000.00' 
C:lO:i "^START 

i;::u.::i process: 
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As you break an application down into more manageable parts, you 
might want to have a separate user-defined function for each part. For 
example: 

V r^":i:nterest 
i:::l::i r^- in put 

i::2::i reprocess r 

!:3:;i RfOUTPur r 



? xm:nput 

i:::i.::i start: 'enter the interest rate, years, and principal 
i:2::i xhh 

i:3::i -k <xi::i::i:::i.b) , <xi::2::i>»i.o>, (xi::3::i::-5()onoo))/Ei.,E2,E3 
i:m:i "^0 

i::5::i eii'the interest rate is greater than :i.b percent* 

Z61 ■•M5TART 

i::?::! e2;'the number of years is greater than i+o- 
i:bi -^start 

C 9 ::i E3 : • the P R I NC I pal I S G re ate R than 5 O 0.00' 

i::lo:j -^start 



\? C I <•• PROCESS INPUT; A; B 

r:.i.::i a<"I+o.oiwinputi::i;j 

i::2:3 b^a«inputi::2::i 

i::3::i cif-iNPUTi::3:iKB 



V RfOUTPUT CI 

i:::i.:] r^'the interest earned is: ', i.o 2 ^ci 
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CONCLUSION 

When programming for an application using the 5110, break the 
application down into manageable parts. To do this, first focus on the 
program output. This is the primary interface to the user. It also 
defines what the real purpose of the program is. Next, consider all the 
input data that is required to generate the output. Finally (and only 
then) plan the actual processing. 

Thinking in this way should help you make the transition from knowing 
the APL language to being able to use the APL language to generate 
user-defined functions for specific applications. 
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Chapter 3. APL Language Elements 



In this chapter, the following topics concerning the APL language 
elements are discussed: 

• Variables 

• Data representation 

• Arrays 

• Examples of useful APL statements and user-defined functions 



VARIABLES 



You can store data in the 5110 by assigning it to a variable name. 
These stored items are called variables. Whenever the variable name 
is used, APL supplies the data associated with that name. A variable 
name can be up to 77 characters in length with no blanks; the first 
character must be alphabetic, and the remaining characters can be any 
combination of alphabetic, and numeric characters. The <■ (assignment 
arrow) is used to assign data to a variable: 

LENGTHf-6 

WXDTH<-8 

AREA^-LENGTHmWXDTH 

To display the value of a variable, enter the variable name: 

LENGTH 
6 

WIDTH 
8 

AREA 
MB 
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DATA REPRESENTATION 



Numbers 



The decimal digits through 9 and the decimal point are used in the 
usual way. The character ~, called the negative sign, is used to denote 
negative numbers. It appears as the leftmost character in the 
representation of any number whose value is less than zero: 



O-'l- 
"3 •■ 



The negative sign, , is distinct from - (the symbol used to denote 
subtraction) and can be used only as part of the numeric constant. 



Scaled Representation (Scientific Notation) 

You can represent numbers by stating a value in some convenient 
range, then multiplying it by the appropriate power of 10. This type of 
notation is called scaled representation in APL. The form of a scaled 
number is a number (multiplier) followed by E and then an integer (the 
scale) representing the appropriate power of 10. For example: 

Number Scaled Form 

j Multiplier 

66700 6.67 E4 

1 -Scale 

.00284 2.84E"3 

The E (E can be read times 10 to the) in the middle indicates that this 
is scaled form; the digits to the right of the E indicate the number of 
places that the decimal point must be shifted. There can be no spaces 
between the E and the numbers on either side of it. 



Numeric Value Range 

Numeric values in the 5110 can range from ~7.237005577332262E75 
to 7.237005577332262E75. The smallest numeric value the 5110 can 
use is ±5.397604346934028E "79. 



Numeric Value Precision 

Numbers in the 5110 are carried internally with a precision of 16 
significant digits. 
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Character Constants 

Zero or more characters enclosed in single quotes, including 
overstruck characters and blank characters (spaces), is a character 
constant. The quotes indicate that the characters keyed do not 
represent numbers, variable names, or functions, but represent only 
themselves. When character constants are displayed, the enclosing 
quotes are not shown: 

• ABCDEFG • 
AJBCDEFG 

M. 23 ABC 
123 ABC 

Mf'THE ANSUER IS: ' 

M 
THE ANSWER IS; 

When a quote is required within the character constant, a pair of 
quotes must be entered to produce the single quote in the character 
constant. For example: 

'DON''T GIVE THE ANSWER AWAY' 
DON'T GIVE THE ANSWER AWAY 



Logical Data 

Logical (Boolean) data consists of only ones and zeros. The relational 
function (> ^ = < ^ '') generate logical data as their result; the result 
is 1 if the condition was true and if the condition was false. The 
output can then be used as arguments to the logical functions 
(a V AT ^ C' ) to check for certain conditions being true or false. 
Logical data can also be used with the arithmetic functions, in which 
case it is treated as numeric 1 's and O's. 
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ARRAYS 



Array is the general term for a collection of data, and Includes scalars 
(single data items), vectors (strings of data), matrices (tables of data), 
and arrays of higher dimensions (multiple tables). All primitive (built-in) 
functions are designed to handle arrays. Some functions are designed 
specifically to handle arrays rather than scalars. Indexing, for example, 
can select certain elements from an array for processing. 

One of the simplest kinds of arrays, the vector, has only one 
dimension; it can be thought of as a collection of elements arranged 
along a horizontal line. The numbers that indicate the positions of 
elements in an array are called indices. An element can be selected 
from a vector by a single index because a vector has only one 
dimension. The following example shows assigning a numeric and a 
character vector to two variable names, N and C; the names are then 
entered to display the values they represent: 

N^5 6.2 "3 88B 95.12 
N 
5 6.2 -3 BBB 95.:l.2 
(::<• ■ ABCDEFCJ ' 

ABCDEFG 
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Generating Arrays 

The most common way to generate an array is to specify the shape 
the array is to have (that is, the length of each coordinate) and the 
values of the elements of the new array. The APL function that forms 
an array is the reshape function. The symbol for the reshape function 
is p. The format of the function used to generate an array is XpY, 
where X is the shape of the array and Y represents the values for the 
elements of the array. For the left argument (X), you enter a number 
for each coordinate to be generated; this number indicates the length 
of the coordinate. Each number in the left argument must be 
separated by at least one blank. The values of the elements of the 
new array are whatever you enter as the right argument (Y). The 
instruction 7pA means that the array to be generated has one 
dimension (is a vector) seven elements in length, and that seven 
values are to be supplied from whatever values are found stored under 
the name A. It does not matter how many elements A has, as long as 
it has at least one element. If A has fewer than seven elements, its 
elements are repeated as often as needed to provide seven entries in 
the new vector. If A has more than seven elements, the first seven 
are used. The following examples show generation of some vectors: 

7p:l. 2 3 
1 2 '3 1 2 3 .1. 

2p;l.23 
;l.23 :123 

5pl .3 
.1. .3 :l . 3 .1. .3 1 . 3 :l. . 3 
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An array with two coordinates (rows and columns) is called a matrix. 
Columns 



1 



9 10 11 12j 



Rows 



To generate a matrix, you specify X (left argument) as two numbers, 
which are the lengths of the two coordinates. The first number in X is 
the length of the first coordinate, or number of rows, and the second 
number is the length of the second coordinate, or number of columns. 
The following example shows how a matrix is generated: 





H<-2 3pl 2 3 LI- 5 6 




M 


1 2 


3 


M- 5 


6 




M<"2 M-p'ABCDEFGir 




H 


ABCD 




EFGH 






m<"2 3pH 




Ml 


ABC 




DEF 





Note that the values in the right argument are arranged in row order in 
the arrays. If the right argument has more than one row, the elements 
are taken from the right argument in row order. 
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The rank of an array is the number of coordinates it has, or the 
number of indices required to locate any element within that array. 
Scalars are rank 0. Vectors have a rank of 1, matrices have a rank of 
2, and N-rank arrays have a rank from 3 to 63 (where N Is equal to the 
rank). N-rank arrays, like matrices, are generated by providing as the 
left argument a number indicating the length for each coordinate (for 
example, planes, rows, and columns). The following examples show 
how to generate 3-rank arrays. Note that the elements taken from the 
right argument are arranged in row order: 



ABCD 
EFBH 

:r.ji<L 

MNOP 
QRST 
UVUX 



A^- ' AB(::DEr-GH:i: JKLMNOPC^RBTUVyXYZ ' 
2 3 MpA 



2-Plane, 3-Row, 4-Column Array 



i|- 3 2('.)A 



AB \ 

9? ^ 4-Plane, 3-Row, 2-Column Array 

El" 

(3 1 -I 
IJ 
KL 

HN 
OP 
QR 

ST 
UV 
UX 
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Finding the Shape and Rank of An Array 

Once you have generated an array, you can find its shape (number of 
elements in each coordinate) by specifying p (shape function) with 
only a right argument, which is the name of the array. If A is a vector 
with six elements and you enter pA, the result is one number because 
A is a one-dimensional array. The number is 6, the length (number of 
elements) of A. The result of the shape function is always a vector: 

A^-lll 222 333 •+'+'4- 555 666 
pA 

6 
The shape of a matrix or N-rank array is found the same way: 





M<"2 


Zpl 2 


3 '+ 5 6 




M 






:l. 2 


3 






•■I- 5 


6 
pVi 






2 3 










R<-2 


3 M-Pl 


2 3 >+ 5 6 1 8 




R 






1 2 


3 •+ 






5 6 


1 8 






1 2 


3 M- 






5 6 


1 B 






:l 2 


3 M- 






5 6 


1 8 
f>R 






2 3 •• 


1- 







In some cases, it might be necessary to know just the rank, the 
number or coordinates (or indices) of an array. To find the rank, enter 
p p (shape of the shape) and a right argument, which is the name of 
the array: 

AM 1:1. 222 333 M-M'l- 555 666 
B<-2 3p:L 2 3 >+ 5 6 
C<-2 3 "+pl 2 3 •+ 5 6 1 



6 
1 

2 3 
i> 

2 3 M- 
3 



pA 

PPA 

pB 

PPB 

pC 

PPC 
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The following table shows what the shapes and ranks are for the 
various types of arrays: 



Data 
Type 

Scalar 



Shape pX 

No dimension (indicated 
by an empty vector). 



Vector 


Number of elements. 


Matrix 


Number of rows and the 




number of columns. 


N-rank 


Each number is the length 


arrays 


of a coordinate. 


Empty Arrays 





Rank ppX 


1 



N 



Although most arrays have one or more elements, arrays with no 
elements also exist. An array with no elements is called an empty 
array. Empty arrays are useful when you are creating lists (see 
Catenation in this chapter) or branching in a user-defined function. 

Following are some ways to generate empty arrays: 

• Assign lO to a variable name to generate an empty vector: 



EVECTOR^-xO 
EVECnOR 



PEVECTDR 



v 



An empty array is indicated 
by a blank display. 

The shape of the empty vector 
is zero (zero elements). 

Use a zero length coordinate when generating a multidimensional 

array: 

This matrix has three rows and no (0) 
columns. If one of the coordinates is 
not zero, you cannot generate the 
empty array. 



EJiATR:i:Xlf-3 Op\0-H 
EHATRIXl 



PEHATRXXI 



3 



A Blank Output Display 



• A function might generate an empty vector as its result; for 
example, finding the shape of a scalar: 



P' A 



A Blank Output display. 
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INDEXING ARRAYS 

You may not want to refer to the whole array but just to certain 
elements. Referring to only certain elements is called indexing. Index 
numbers must be integers; they are enclosed in brackets and written 
after the name of the variable to which they apply. Assume that A is 
assigned a vector as follows: A-«-11 12131415161 7. The result of 
entering A is the whole vector, and the result of entering A[2] is 1 2 
(assuming the index origin is 1). 

Here are some more examples of indexing: 

AfJ.1 12 1.3 IM- 1.5 1.6 1.7 
A 1:3:1 
13 

A 1:5 3 7 i::i 

V5 13 17 11 

^^■■■^^ •■•• '■'■ ^^ Blank Character 

ai::b:i 

13 11 1'+ 16 

B<- ' ABCDEFGH 1 JK LMNO PQ RSTU VWX YZ 

Bi::'i- 1 iM- 27 1 m m- 27 3 12 1 9 ib:i 

DAN AMD CLAIR 

C<-22 9 IB 7 9 li-l- 9 1 

bi::(:;:j 
virginia 

If you use an index that refers to an element that does not exist in the 
array, the instruction cannot be executed and INDEX ERROR results: 

A 
11 12 13 1>I- 15 16 17 

ai::b:j 
index error 
ai::b:i 



You cannot index or do anything else with an array until after the array 
has been specified. For example, suppose that no value has been 
assigned to the name Z; then an attempt to store values in certain 
elements within Z would result in an error, because those elements do 
not exist: 

zi:3 m^-iB ii-6 

VALUE ERROR 

Zi::3 MiJ^" IB M6 
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indices (whatever is inside the brackets) can be expressions, provided 
that when those expressions are finally evaluated, the results are 
values that represent valid indices for the array: 

B 

abcdef(3h:i:jklhnopqrstuvwxyz 

Xi-1 2 3 H- 5 

bi:xh2:i 

BDFHJ 

X 
1 2 3 »+ 5 

Bi::i+x><3::i 

DGJMP 

The array from which elements are selected does not have to be a 
variable. For example, a vector can be indexed as follows: 



2 3 5 7 9 :i.:L :i.3 15 1.7 i.9i::7 2 •+ 2:3 

13 3 7 3 

'ABCDEFGHIJKLMNOPQRSTUVUXYZ 'i::i2 15 15 11 27 16 11 
LOOK PA 

•ABCDEFGHIJKLMNOPQRSTUVUXYZ ' 1:2 «l-<oM- 15 lt+ 27 13 1 18 25! 
DON 
MARY 



Indexing a matrix or N-rank array requires an index number for each 
coordinate. The index numbers for each coordinate are separated by 
semicolons. Suppose M is a 3 by 4 matrix of consecutive integers: 

M<"3 '+<!>xl2 

If you ask to see the values of M, they are displayed in the usual 
matrix form: 

M 

1 2 3 »+ 

5 6 7 8 

9 10 11 12 

If you want to refer to the element in row 2, column 3, you enter: 

mi:2;3:j 



If you want to refer to the third and fourth elements in that row, you 
enter: 

Mi:2;3 "•!•;] 

7 8 
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Similarly, to refer to the elements in column 4, rows 1, 2, and 1, you 
enter: 

Mi::i 2 :i. ;'i::i 

L|. s M- 

You can use the same procedure to select a matrix within a matrix. If 
you want the matrix of those elements in rows 2 and 3 and columns 1, 
2, and 1 of M, you enter: 

M[:2 3; :i. 2 :l::i 

5 6 15 
9 :l.0 9 

If you do not specify the index number for one or more of the 
coordinates of the array that you are indexing, APL assumes that you 
want the entire coordinate(s). For instance, to get all of row 2, you 
enter: 

iii::2;:i 

5 6 7 B 
Or to get all of columns 4 and 1, you enter: 

u- 1 
e !5 

.1.2 9 

Note: You still have to enter the semicolon to make clear which 
coordinate is which. The number of semicolons required is the rank of 
the array minus one. If the correct number of semicolons is not 
specified, RANK ERROR results: 

M«"3 i\p\12 
3 i|- 

mi:;6::M"9 
rank error 
m:6:u-9 

A. 

You can change elements within an array by assigning new values for 
the indexed elements. (The rest of the array remains unchanged.) 

A^-3 3p:l. 2 3 M- 5 6 1 8 9 

A 
:l. 2 3 
f|- 5 6 
1 i;j 9 

Ai::2;2 3::h":i.o 20 

A 



J) 



1 2 
ii- 10 20 

1 B 9 
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JOINING ARRAYS TOGETHER 

You can join two arrays to make a single array by using the catenation 
or lamination functions. The symbol for these functions is the comma. 



Catenation 

When catenating vectors, or scalars and vectors, the variables are 
joined in the order in which they are specified. For example: 





AM 




3 


M- 




Bfi.|. 


5 


6 






A ; B 








1 2 3 


B,A 


5 


6 




i-l- 5 6 


1 2 
A, 2 


3 


L|. 




I 2 3 


M- 2 
3, A 








3 1 2 


3 M- 









When catenating two matrices or N-rank arrays, the function can take 
the form A,[I]B, where I defines the coordinate that will be expanded 
when A and B are joined. If the coordinate is not specified, the last 
coordinate is used. When A and B are matrices and [I] is [1], the first 
coordinate (number of rows) is expanded; when [I] is [2], the last 
coordinate (number of columns) is expanded. The following examples 
show how to catenate matrices: 



A^- 
Bf 



2 3p1.0 
2 3p1.1. 



20 



30 i|0 

33 i-m 



50 60 
55 66 



Graphic Representation 

A B 



10 20 30 
40 50 60 



11 22 33 
44 55 66 



10 
J-l-0 



:l.O 

l+O 



10 
1+0 
11 

l.|.L|. 



A;B 

20 30 11 
50 60 Lm 

A j:2:iB 

20 30 11 
50 60 Ij-M- 

Aj::i:iB 

20 30 

50 60-^ 

'.■> O X "K 

55 66 



':>':> 



oo 



33 
66 



33 
66 





/V 








B 




10 


20 


30 


11 22 


33 


40 


50 


60 


44 55 


66 


A 




10 
40 


20 
50 


30 
60 






B 


11 


22 


33 








44 


55 


66 







APL Language Elements 25 



Arrays of unequal sizes can be catenated, provided that the lengths of 
the coordinates not specified are the same (see the first example 
following). If the coordinates not specified have different values, an 
error results (see the second example following): 



A<-2 3pl{) 
B<"2 ij-pll 



20 30 
22 33 



«+0 



iO 



60- 
66 



10 
40 

77 BB 



20 
50 



30 
60 



11 
55 



22 

66 



33 
77 



44 
88 



aj::2:jd 

10 20 30 :U. 22 33 M'l- 
i-M) 50 60 55 66 77 BB 



A 












B 


10 
40 


20 
50 


30 
60 


11 
55 


22 
66 


33 
77 


44 
88 



A,i::.i.:iB 

.ENGTH ERROR-*- 
Aj:iJ B 



10 


20 


30 


^^ 


40 


50 


60 


m 


11 


22 


33 


44 


55 


66 


77 


88 



A scalar can also be catenated to an array. In the following example, a 
scalar is catenated to a matrix. Notice that the scalar is repeated to 
complete the coordinate: 



Af-2 3plO 20 30 «l-0 50 60 
A 

10 20 30 
•M) 50 60 

A, t:2;:i99 

10 20 30 99 
MO 50 60 99 

A j::i::i99 

10 20 30 
'l-O 50 60 
<j>(j> y<j> 9<j> 

A vector can also be catenated to another array, provided the length 
of the vector matches the length of the coordinate not specified. See 
the following examples: 



A, 99 8B 
10 20 30 99-^ 
«-l-0 50 60 BB 



10 



40 



20 



50 



30 



60 



99 



88 



A j:i::i99 bb 

LENGTH ERROR 

A,i::i:3 99 bb 

A 



10 


20 


30 


40 


50 


60 


99 


88 


m 
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The catenate function is useful when you are creating lists of 
information. Sometimes it is necessary to use an empty array to start 
a list. For example, suppose you want to create a matrix named 
PHONE where each row will represent a seven-digit telephone number. 
First you want to establish the matrix, then add the telephone numbers 
at a later time. The following instruction will establish an empty array 
named PHONE with no (0) rows and seven columns: 

PHONE<"0 7pxO 

'^'"^•'^'•" Blank display indicates an 

"* empty array. 

P PHONE 
1 

Now, the telephone numbers can be added as follows: 

PHONED" PHONE , i: :l. ::i " 5336686 ' 
PHONE 
5336686 

PHONED- PHONE, i:::i.::i ' ||-56M-77:l ' 

PHONE 
5336686 
M-56'1771 

P PHONE 
2 7 

\ The list of telephone numbers 

now contains two rows. 
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Lamination 



When laminating two variables together, the function joins the 
variables together by creating a new coordinate. The function takes 
the form A,[I]B, where I is an index number that must be a fraction. 
This index number specifies where the new coordinate is added. If the 
index number is less than 1 , the new coordinate is added before the 
first coordinate; if the index number is between 1 and 2, the new 
coordinate is added between the first and second coordinate; and so 
on. For example: 



Graphic Representation 



AAA 
AAA 
AAA 



BBB 
BBB 
BBB 



A<"3 3p*A 
A 



B<"3 3p'B 
B 



A 


A 


A 


A 


A 


A 


A 


A 


A 




B 


B 


B 


B 


B 


6 


B 


B 


B 



AAA 
AAA 
AAA 

BBB 
BBB 
BBB 



c<-A, i:.3.::iB 



BlBlBl 


A 


A 


AT 


A 


A 


AT 


A 


A 


A 



■The new coordinate is added before 
the first coordinate. 



2 3 3 
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c<s-A,i::i. . :i.::iB 
c 



AAA 
BBB 

AAA 
BBB 

AAA 
BBB 

3 2 3 





lAAh 




aIaIaFI 


A 


A 


Aj 


— 1 


B 


B 


B 





pC 



The new coordinate is added between the 
first and second coordinate. 



c^A, i:2.:i.:jb 
c 



AB 
AB 
AB 

AB 
AB 
AB 

AB 
AB 
AB 

3 3 2 



aIb ^ 


A 


bbT 


A 


Bj 


A 


b 



pc 



The new coordinate is added after the 
second coordinate. 



APL Language Elements 29 



The new coordinate is always 2 because two variables are joined 
along a new coordinate. 

Unless one of the variables is a scalar, arrays of unequal sizes cannot 
be lanninated together. For example: 



A<"3 Zi^\9 

A 
Z 
6 
9 

Cf-A, 

C 
2 3 
S 6 
8 9 



1 1 1 



lOllOlO 


1 


2 


30 


4 


5 


60 


7 


8 


9 



10 1.0 
10 10 

10 10 

B 

11 12 
11+ 15 

Bj:: 

LENGTH ERROR 

B , i:: 0.13 A 



10 
10 
10 



10 
13 



3(!)10 11 12 13 V\ 15 



HP\ 



1011 


12 


13 14^5] 



1 


2 


3 


4 


5 


6 


7 


8 


9 
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USEFUL APL STATEMENTS AND USER-DEFINED FUNCTIONS 

To remove duplicate blanks from a character vector: 

ycoM pressing:!? 

V Z<-CDMPRESB \4',1 

\: 1 ::i Zf- 1 4- < ci <d x > ?: i fW::= • • > /y <•• ■ • , y 
y 

COMPRESS 'AAA / BBBB CCC DBD 
AAA BBBB CCC DBB 

The right argument is the character vector. 

To create a matrix from a character vector with a delimiter for each 
row: 

VFORMrrny ^aiO will be set to just during 



V iif-D FORM S;A;B;X;Z;niO^^ the execution of this function. 

i:ii i:]IO<-0 

1:23 M^(X<-Si!*SB)/S<-,S 

1:33 Z<-(X?^l-tX,^-ltX>/l*xpX 

i:«+3 M<- ( < pA ) , B ) f> ( , ( A-:i. ) « . > t B^o r r/A<-xi::z-:i. ;:i/z-o , " :i. ^z ) \m 

'o' FORM "AoB^CCC^D" 

A 

B ^ 

QQQ In this example, the o character is used 

H as the delimiter. The left argument specifies 

the delimiter, and the right argument 

specifies the character vector. 
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To remove the alphabetic characters from a character vector, leaving 
only the numeric characters and blanks: 

V REMOVE i:o:iv 

V NEW*- REMOVE OLD 

L" 1 :\ NEW<" ( OLD*- ' 1. 'J^^S^SATB? . * ) /OLD 
V 

OLDf-'DAN 30 DAVE 29.5 JERRY 37 MEL »+().8 
REMOVE OLD 
30 29,5 37 i-l-O.B 

To replace all trailing blanks with a minus sign: 

VBLANKSCITJV 

V Z^BLANKB M;V 

i::i::i Vf-,(DA\0M===' ' 

121 Zf-,M 

1:3:3 zi::v/\pvj<"' •■ 
i:"+:i z<-(pM)r»z 

V 

MAK-2 5p'AB CDE ' 

MAT 
AB 
CDE 

BLANKS MAT 

AB -••■ 

CDE--- 

Return all elements of a vector that are even numbers: 

VEVENi:i:;i::iv 

V ZfEVEN V 
111 Z<"<0:=--=2!V)/V 

V 

EVEN 12 3 ^■ 5 6 7 B 9 
2 M- 6 8 

To delete all comment lines from a user-defined function: 

vcoMMENTi::n:iv 

V COMMENT FN;M 

1: 1 :i M*"OFX < Mt: ; :i ::i5!<5 • rt ■ ) /m<"|:icr fn 

V 

VADD 
1:1 ::i ft COMMENT LINE 1. 

i::2:j 3-m-i- 

1:3:1 ft COMMENT l:i:ne 2 

r.'+:i y 

COMMENT ' ADD ' 

VADDi:o:iv 

V ADD 
til 3-f-M. 

V 
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To merge two variables with the same shape into a single vector: 

VMERBEiniV 
? Z^A HERGE B 

y 

A^2 2p'A' 
BM* 2r:)'B' 

A HERGE B 
AAAABBBB 

To delete duplicate elements in a vector: 

yDUPL;i:cATEi::rpv 

y Z<"DUPLICATE V 

i::i.:i z<"(< xcW):«vxV)/v^,v 

V 

DUPLICATE 1233M-25655I5 
1 2 3 «+ 55 6 

To find the first nonblank character in a character vector: 

VN(:)NBLANKi::o:3V 

V Z^-NQNBLANK U 
i::U 2i"lt i\4-^' ')/W 

V^ ' DAN ' 

NONBLANK V 
D 

yNONBLANKXi::i;ny 

V Z<"NONBLANKX W 
111 Zi"i<\W'' ')/W 

NONBLANK X V 
D 
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To determine whether a variable is character or numeric: 



:l::i 



?DETERMXNEi::[:i:jv 

V DETERIilNE W 

■NC'i::i:ixo»(":i.t2tit,w) 



A«- * 9 ■ 
B^9 



DETERMINE A 
DETERMINE D 



The result is C for character or 
N for numeric. 



VDETERMINEinriy 
V DETERMINE! W 

•NC 1:1:3 10*' '===:i.tOpy:i 



N 



DETERMINE! A 



DETERMINE! B 



To make scalar or vector into a matrix: 

VMATRIXLIIPV 
y Z^-MATRIX M 

i::!::i z<"("2t!, i, c>M)pM 
y 



A«" ■ ABCDEFG ' 

X<" MATRIX A 

X 
ABCDEFG ^ 

PX 
1 7 



The result is a 1 by 7 matrix. 



To delete all user-defined function names starting with a specified 
character vector from the active workspace: 

yDELETEFNi::o::iy 

y DELETEFN c.:NL;Z;X 
1:: ! :] Z<- ( ( ( ( ! t pNL ) , pC ) t NL ) a . ..(;;<- , C ) /HLi" < ! t C ) ONI... 3 
1:2:1 Xf-OEX Z 

y 



yADDt:o:iy 
y ADD .^ 
\:.i:\ 3MI- 
y 



A user-defined function in the 
active workspace 



DELETEFN ' AD ' 
ADD 
VALUE ERROR 
ADD 



The function is no longer in the 
active workspace 
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To count the number of occurrences of each unique character in a 
character vector: 

vcouNTi;o::i'i? 
? Zf-COUNT y;uc 

COUNT ' ABBCCCDDDDE ' 
:l. 2 3 i+ ;l 

COUNT 'ABCDBCDCDD* 
:l 2 3 M- 



To center the character string in each row of a character matrix: 

vcENTERi::ri::i? 

V ZfCENTI£R M 

i:: 1. :i n- ( ■■■■ r < •*•/ a\(|)m~- ■ • > ^2 > <I)M<- < •♦•/ A\i^r: ■ ■ > (Dm 



MAT<"3 6p' A B C 

MAT 
A 
B 

C 

CENTER MAT 
A 
B 
C 

To right-justify the character string in each row of a character matrix: 

V RIGHT JUST :i:FYr.:n:i? 

7 ZfRIGHTJUSTIFY M 

i:: 1 1 z<" ( • ••*/a\ < (DM ) - ' ' > (DM 

7 



MAT 



A 
B 



RIGHTJUSTIFY MAT 
A 
B 
C 
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To left-justify the character string in each row of a character matrix: 



i:: 1 1 



vLEFTjuBTi.FYi::i::i:w 

7 Z^-LEFTJUSTIFY M 
Z<-(+/a\M~' ■)t|)M 



3:1 

m:i 
5:1 

61 

7::i 

b; 

9; 



i:bi 
i 



A 



B 



c: 



HAT 



LEFTJUGTIFY MAT 



To list each user-defined function in the active workspace: 



V 



:r : Fi 



IN; COL; NO; 1:1:1:0 
ALL funct:i:onb 
:i:sTVARS. 



:i:n the 



i::i 
i::l 
i::i 
i:i. 
1:: 1 
1:: :i. 
i::i7:i 



VL:i:BTFNSi::n::iv 

LISTENS ;ALF;N AMI: 

nTHT.s funct:[on lists 

tt EXCEPT LISTENS AND 
UUU~1 

i::iPWM.32 

NAME^-GNL 3 

ALF<- ■ ABCDEFGHIJKLMNOPqRSTUVW:KYZ ' 

ALF<"ALF , ' AABCDEFGHIJKLMNOPQRSTUVUXYZA 

ALF^"ALF, ' Ol23M'56789'" 

NAME<-NAMEi::<^66.i. ALE \ felNAME ; ::i 

I4"0 

LOOP : -K ( 1. 1 pNAME ) < I*-I*:i. ) /() 

■^ ( A/NAME r.: I ; 1=^:= ( "• 1. 1 pNAME ) t 

-> < a/namei:: i ; ::i==== ( ' 1 1 pName > t 

HQi- 1 1 pFUNf-oc R NAME i: I ; ::i 

C0L<- < ( NO , :i. ) p ■ i:: ■ ) , < T ( NO , :i. ) p • 1 ■*• u>^o ) , ( < no , 2 ) p ■ ::i ■ > 

C0Li::i. ; i<-("itpCOL)t ' ' 

COL, FUN 
2 1. p- ■ 
-H...OOP 



ACTIVE UORK SPACE 



LISTENS' ) 
LISTVARS" 



/LOOP 
)/LOOP 



V 
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3::i 
ii-:i 



LISTENS 
Zi-BLANKS M;V 
V<- , (Da\(DM-- ■ ■ 

Z[:v/\pv::h-'-' 

Z<-(pM)pZ 



Z<-A BY B; ROW 

:i.::i A<-(2t(pA), .1. :i. )pA 



iSTFNS[:is:i 



The ATTN key was pressed before 
all the functions in the active 
workspace were listed. 
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To list each variable and associated value in the active workspace: 

yL:i:sTVARBi::i:i::i'y' 
7 L :i: ST VA RB ; alf ; V A R ; :i: ; r ; i:;i i o 

\:il ftTHIB FUNCTION LIST THE VARAIBLFS IH THF ACTIVE yORKSPAC 

1:2:1 o:i:of-.i. 

1:3:] R<-:l.tpVAR<"i:jNI... 2 

mi ALF<- ' ABCDEFGHJ: JKLMNOPQRSTUVWXYZA ' 

1:5:1 ALF<"ALF , • ABCDEFGHJ. JKLiiNOPQRSTUVyXYZA ' 

C:6:i ALF<-ALF , ' Ol23M-56789' "■-" " 

i:?:i VAR^-VARi:*6A.i. ALF \ feiVAR ; :i 

r:B:.i n-i) 

1:9:1 logp:-*(R-.:i:m-41)/o 
1:1.0:1 2 1 p' ' 
i:i.:i.:i .*.i:.n-' " ,vari:t. ; :i 

i::i.2:3 ••h...ogp 
y 

LIBTVARS 



1.0 


20 30 


i+O 


50 60 




B 


1.1 


22 33 


l.|.L|. 


55 66 




c: 


AAA 


1 


B 





The ATTN key was pressed before 
all the variables in the active 
workspace were listed. 



J ST V A RS 1:1.2: 

To field-protect high-order digits: 

vpRGTi:n:iy 

V Zf-N PROT V 
1:1. :i Z<"(-N)t( <N-3)f>'M' ) ,v 
7 

1.0 PROT ■1.23.I-I-5' 
•>t«-»)tl23.M-5 
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To delete leading blanks from a character string: 

vDLBi::n:iv 

7 li-ULB A 

y 

DLB ■ 1 23. 1-1-5 ■ 

123.1-1-5 

To join vectors and print results as a single, sorted vector: 

7joj:Ni::n::iv 

V Z<"A JOIN B;T 

r:ii z<-t[:*t<-A;B:i 

A<":l.0 5 6 2 3 1 
B<-:l.5 5 2 2 7 

A JOIN B 
12223556 7 10 15 

vjG:i:Nii::i::i::iv 

V Z<"A JOINI B;T 

c:i:] z^"T[:'|'T<"A,b:i 

V 

A JOINl B 
15 10 765532221 
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To sort up to the first nine columns of a matrix with each row 
representing a name: 



vSGRT!:;o;:!? 

? Z^-SORT LIST; ALF 

!" 1 ;:i A i... !•■■ ^" ' A B C D E F G i-i 1 J K 1... M N P Q i^ 8 I' i J V W X Y Z ' 

i: 2 :! Z f • L= 1 8 T i: ii 2 9 .1. A !... F \ ^i L 1 8 T ; 1 

y 

U"6 7p' JENNY JAN LUCY ARCHIE DGUGLASBETH 

L 
JENNY 
JAN 
LUCY 
ARCHIE 
DOUGLAS 
BETH 

L^8GRT L 

L 
ARCHIE 
BETH 
DOUGLAS 
JAN 
JENNY 
LUCY 



To find the location of a name in a list of names: 

vFiNDi::i:]::iv 

? Z^LIST FIND NAME 

i:: 1 :i H- < ( LISTa . :::: < ••• 1. t pLIST ) tNAME ) ) / \ :l. t pLIS' 

V 

L FIND 'JAN' 
«-|. 

To delete a name from a list of names: 

yDELi::n:.i'v' 

? Z<"LIST DEL NAME 

i::i:3 n-i (^^lista . :=-•< "it plist) tNAME) )/list 

L DEL 'JAN' 
ARCHIE 
BETH 
DOUGLAS 
JENNY 
LUCY 
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To perform a specified operation if a condition is true: 

y iFi: 1:1:1 V 

V Zi-OP If COND 

i::i:i z<"COND/gp 
y 

:!:■<•■ 3 

'pr:i:nt' if :d===3 
pr:i:nt 

'pr:i:nt' :i:f :i:=^=-»-i- 
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Chapter 4. Active Workspace Control 



The active workspace is the internal storage where calculations are 
performed; it is also the place where variables and user-defined 
functions are stored. The 5110 system commands, system functions, 
and system variables are used to control the active workspace. In this 
chapter, the following topics are discussed: 

• The active workspace environment in a CLEAR WS 

• Getting information about the active workspace 

• Changing the active workspace environment 

• Getting data into the active workspace 

• Active workspace storage considerations 
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THE ACTIVE WORKSPACE ENVIRONMENT IN A CLEAR WS 

When the 5110 is first turned on, or the RESTART switch is pressed, 
or the )CLEAR command is executed, the active workspace 
environment has the following characteristics: 

• The index origin (DIO) is 1. 

• The comparison tolerance (DOT) is 1E-13. 

• The random number seed (DRL) is 16807. 

• The print width (DPW) is 64. 

• The print precision (DPP) is 5. 

• The latent expression (DLX) is an empty vector. 

• The workspace identification [ )WSID ] is CLEAR WS. 

• The number of symbols allowed [ )SYMBOLS ] is 125. 

(See the /BM 5110 APL Reference Manual, SA21-9303, for a complete 
description of the system variables and system commands.) 

These characteristics control the way some of the APL functions and 
system commands will work in the active workspace. For example, if 
you have assigned 125 variable names and you enter the statement: 

NAHE1.26<"' ROCHESTER' 
SYMBOL TABLE FULL 

NAME :i. 26 

A 

a SYMBOL TABLE FULL error message is displayed, because only 125 
symbols (names) are initially allowed in the active workspace. How 
you change some of the active workspace environmental 
characteristics is discussed next. 
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CHANGING THE ACTIVE WORKSPACE ENVIRONMENT 

You can change the system variables, workspace identification 

[ )WSI D ] , and number of symbols allowed [ )SYMBO LS ] . For the 

system variables, you simply assign them a new value. For example: 



lO^-O. 



■ The index origin is now 




The number of symbols allowed in the active workspace can be 
established only in clear workspace. That is, the size of the symbol 
table must be established by the 5110 before any other data is placed 
in the active workspace. 



Symbol Table. Eight bytes of active 
workspace storage are reserved for 
each symbol allowed. 



Active Workspace 

The number of symbols allowed is initially set to 125, which requires 
1000 bytes of active workspace storage. 

There might be times when you have used the maximum number of 
symbols allowed, so you may need to increase the maximum number 
of symbols allowed. If you change the number of symbols allowed in 
a clear workspace and then use the )LOAD command to load a stored 
workspace into the active workspace, the number of symbols allowed 
is the same as when the stored workspace was written to the media. 
However, you can use the following procedure to change the number 
of symbols allowed: 

1. Save the contents of the active workspace using the )SAVE 
command. 



2. Clear the active workspace using the )CLEAR command. 

3. Set the new number of symbols allowed using the )SYMBOLS 
command. For example: 



) SYMBOLS 251.-^- 
WAS 125 



Now, 251 symbols are allowed. 
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4. Copy the stored workspace into the active workspace using the 
)COPY command. Using the )COPY command does not affect the 
number of symbols allowed in the active workspace. The )COPY 
command is discussed later in this chapter. 

The workspace identification specifies the device/file number and file 
ID where the contents of the active workspace are stored when a 
)SAVE or )CONTINUE command is issued. The )WSID command can 
be used to change the device/file number and file ID where the 
contents of the active workspace is to be stored. For example: 

)LDAD 11 01 DATA 
LOADED qiOOl DATAj 

4- This device file number and file ID is now 

) WS 1 D 12 1 TEST associated with the active workspace. 

UAS 11001 DATA 
)SAVIi 




SAVED 120 01 TEST ^v """^^ Change the workspace identification. 



Now, when the )SAVE [or )CONTINUE] 
command is issued, the contents of the 
active workspace are written to the new file. 



GETTING DATA INTO THE ACTIVE WORKSPACE 

You can get data into the active workspace by entering the data from 
the keyboard or reading the data from a tape or diskette file. You read 
data from a tape or diskette file using an APL shared variable or one 
of the following system commands: 

• )LOAD 

• )RESUME 

• )COPY 

« )PCOPY 

• )PROC 

See Chapter 10, input /Output Control, for information on reading data 
using APL shared variables. The system commands used for reading 
data into the active workspace are discussed next. 
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The )LOAD and ) RESUME Commands 

The )LOAD and )RESUME commands are used to load an entire stored 
workspace into the active workspace. The contents of the stored 
workspace then replace the contents of the active workspace. The 
)LOAD command has the following characteristics: 

• Loads any stored workspace, which was written to tape or diskette 
by the )SAVE or )CONTINUE command, into the active workspace. 

• If the stored workspace has a latent expression assigned to the DLX 
system variable, the latent expression is executed each time the 
)LOAD command is used to load that stored workspace into the 
active workspace. 

• If the stored workspace has shared variables established, the shared 
variables are not reestablished when the )LOAD command loads the 
stored workspace into the active workspace. 

The )RESUME command has the following characteristics: 

• Loads any stored workspace which was written to tape or diskette 
by the )SAVE or )CONTINUE command into the active workspace. 

• If the stored workspace has a latent expression, the latent 
expression is not executed when the continued (stored) workspace 
is loaded into the active workspace. 

• The primary reason for using this command is to reestablish the 
system environment as it was when the workspace was written to 
the media. That is, if the stored workspace was written to the 
media by the )CONTINUE command, any shared variables and/or 
suspended functions in the stored workspace are reestablished in 
the active workspace by the )RESUME command. See The 
)RESUME Command in the IBM 5110 APL Reference Manual, 
SA21-9303, for a description of how shared variables are 
reestablished. 
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The )COPY and )PCOPY Commands 

The )COPY and )PCOPY commands are used to copy all or selected 
objects (variables or user-defined functions) from a stored workspace 
into the active workspace. When these commands are used, the 
objects are copied into the active workspace without replacing the 
entire contents of the active workspace. When the )COPY command is 
used, any objects already in the active workspace are replaced by the 
objects specified by the )COPY command if the objects have the same 
name. When the )PCOPY command is used, any objects in the active 
workspace are protected and not replaced by the specified objects if 
the objects have the same name. These commands have the 
following characteristics: 

• These commands can only be used to copy objects from a 
workspace written to tape or diskette by the )SAVE command. If 
you want to copy objects from a workspace written to tape or 
diskette by the )CONTINUE command, the stored workspace must 
be loaded into the active workspace and then written to the media 
by the )SAVE command. 

• These commands cannot be used if the active workspace contains 
suspended functions. 

• These commands can be used to copy objects from several stored 
workspaces into the active workspace. 



The IPROC Command 

An alternative to entering data from the keyboard is to get the data 
from a procedure file. A procedure file contains character records that 
represent any input that is possible from the keyboard, such as system 
commands, function definition, and APL expressions. When the )PROC 
command is issued, the 5110 reads and executes one procedure file 
record at a time until the last record (end-of-data) is processed. Then 
the 5110 goes back to using regular keyboard input. [See the IBM 
5110 APL Reference Manual, SA21-9303, for a complete description of 
procedure files and the )PROC command.] 

A procedure file must be a type I or U data file and the records cannot 
be greater than 128 characters. (See Chapter 10, Input /Output 
Control, for a complete description of data files.) 
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A procedure file is useful for doing unattended applications that 
require using system commands and/or function definition. For 
example, assume you have an application that requires several 
user-defined functions. However, not enough workspace storage is 
available to contain all of the user-defined functions. In this case, you 
might: 

1 . Use the )SAVE command to store the user-defined functions on 
tape or diskette. 

2. Create a procedure file that contains the following character 
records: 

a. A )COPY command to copy the first user-defined function(s) 
required for the application into the active workspace 

b. The statement{s) required to execute the user-defined 
function(s) 

c. An )ERASE command that erases user-defined functions and 
variables that are no longer required 

d. A )COPY command that copies the next user-defined 
function{s) required for the application into the active 
workspace 

The previous steps are repeated until the application is complete. 

3. Use the )PROC command to execute the statements from the 
procedure file. After the last statement is read and executed, the 
5110 again accepts input from the keyboard. 

Note: Using the )PROC command requires approximately 800 
bytes of active workspace storage. The active workspace is 
always cleared the first time a )PROC command is used after you 
turn the power on or press RESTART, because the required 800 
bytes can be allocated only in a CLEAR WS. The active 
workspace is not cleared for any subsequent )PROC commands 
because the 800 bytes are already allocated until the power is 
turned off or RESTART is pressed. Therefore, if you have any 
useful data in the active workspace, you should save this data 
before using the )PROC command the first time. 
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INFORMATION PROVIDED ABOUT THE ACTIVE WORKSPACE 



You can get information about the active workspace by simply 
entering certain system commands, system variables, or system 
functions without specifying any parameters or arguments. The 
system commands that provide information about the active 
workspace are: 



System Command 
)SYMBOLS 



Information Provided 

How many symbols are allowed 
and how many symbols are 
currently being used. (The symbols 
consist of labels, variable names, 
user-defined function names, and 
any system variables and functions 
that have been used.) 



)WSID 



)FNS 

)VARS 

)SI 



The current workspace ID and 
device/file number. This 
information specifies where the 
active workspace is stored when a 
)SAVE or )CONTINUE command is used. 
(When a stored workspace is loaded 
into the active workspace, the 
workspace ID and device/file 
number of the stored workspace 
is assigned to the active workspace.) 

The name of the user-defined 
functions in the active workspace. 

The names of the variables in the 
active workspace. 

The names of any suspended functions and 
the statement number where each 
function is suspended. For example: 

Statement 2 of this function 



)s:i: 

f"un(:;t]:onai::5::i 
FUN(:rn:oNBi;:2 
FUNCT]:oN(::r.6 



called FUNCTIONA. 



Statement Number 



)SINL 



Function Name 

The * (asterisk) indicates the suspended 
functions. The functions without an 
asterisk are functions (called pendent 
functions) that called the previous 
function. 

The same information as the )SI command 
plus the names local to each function. 
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The system variables that provide information about the active 
workspace are: 

System Variable Information Provided 

OCT How different two numbers 

must be to be considered unequal. 

DIO The value of the index origin. 

DRL The starting value used in 

generating random numbers. 

DLC The statement number currently 

active. These statement numbers are 
the same as the statement numbers 
displayed by the )SI command. 

DWA The amount of unused storage 

in the active workspace. 

Note: The value of these system variables can be used in APL 
statements. For example: 

^DLC causes a suspended function to resume execution with the next 
statement to be executed. 

The system functions that provide information about the system are: 

System Function Information Provided 

DNL The names of the labels, variables, 

and user-defined functions in 
the active workspace 

DNC The classification (label, variable, 

or user-defined function) of a 
specified name 



ACTIVE WORKSPACE STORAGE CONSIDERATIONS 

Because the 5110 active workspace contains a fixed amount of 
storage, it is good practice to conserve as much storage as possible. 
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Data Types and Storage Considerations 



The following list shows how many bytes of storage are required for 
each data type that can be in the active workspace: 



Data Type 

Character constant 

Variable name (3 
characters or less) 



Variable name (4 
characters or more) 

Whole numbers that are 
equal to or less than 

231 .1 



Number of Bytes Required 

1 byte per character 

1 2 + (4 X rank) bytes 
The rank is the number of 
coordinates (pp variable). 

1 byte per character + 21 
bytes + (4 X rank) bytes 

4 bytes 



Whole numbers that are 8 bytes 
greater than 2^^ -1 



Decimal numbers 
Logical data 



8 bytes 

1 bit (1 byte contains 
8 one or zero bits) 



Note: Storage is always allocated in 4 byte increments. For example, 
the following illustration represents a portion of storage: 



1 byte 




I 



D 



In this example, 
storage has been 
allocated and used 
to this point. Also 
the storage required 
for the variable 
names A, X, and Y 
is already allocated. 



«/ V. 



The statement 
A — 'ABCD' 
allocates and uses 
4 bytes of storage 



The statement 
X -^ 'EF' 
allocates 4 bytes 
of storage, but 
uses only 2 bytes 



The statement 
Y -^ 'GH'uses 
the remaining 
2 bytes. 
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Following are some cohsiderations that can be used to conserve 
storage: 

• Make all objects (variables and user-defined functions) not required 
for use outside of a user-defined function local to the function. 

• Store data in data files on tape or diskette and use an APL shared 
variable (see Input /Output Control) to transfer the data into the 
active workspace when required. 

• Clear suspended functions from the active workspace. 

• Collect user-defined functions by related operations and store each 
set into a workspace; file on the media. Then when a certain set of 
related functions is required to process data in the active 
workspace, the stored workspace containing these functions can be 
copied into the active workspace. When the processing is done, the 
functions can be expunged (DEX) and another set of functions can 
be copied into the active workspace. 

• If a value consists of all I's and O's, store the value as logical data. 
For example, you have the following vector: 

VE(:rroR<£":i.0p<2-:i. ) 

VECTOR 
:l. :l. ;l. :l. 1. 1 1. :l. ;l. 1 



The result is a vector of ten I's, and each 1 requires 4 bytes of 
storage. However, the vector can be changed to a logical vector as 
follows: 



VEcrroR^-iAVEcnoR 
VEcrroR 
:l 1. :l. :l. :l. :l. 1. :l. 1. 1 
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The result looks just like the previous result; however, only 2 bytes 
of storage are required. 

• Because each variable requires at least 12 bytes of overhead, an 
array of six elements requires approximately 60 bytes less storage 
than six separate variables. 

• Names of 3 characters or less require 8 bytes of storage in the 
symbol table (the symbol table is part of the active workspace 
where the names of all the symbols, including variables, 
user-defined functions, and labels, are stored). Names of 4 
characters or more require an additional 8 bytes plus 1 byte for 
each character in the name. 

Note: Even if an object is erased from the active workspace, the 
storage used for its name will not be available for use unless the 
contents of the active workspace are written to the media with a 
)SAVE command and then loaded or copied back into the active 
workspace. 

• Identical names that are local to more than one user-defined 
function do not require additional symbol-table space for each 
function. 

When the contents of the active workspace are written to the media 
by the )CONTINUE command, and that stored workspace is loaded 
into a different 5110 with a larger active workspace, the amount of 
available workspace (DWA) remains the same as it was when the 
contents of the active workspace were originally written to the media. 
To take advantage of the additional storage in the larger active 
workspace, write the contents of the active workspace to the media 
using the )SAVE command, then load the stored workspace back into 
the 5110. Also, for the same reason, a workspace written to the 
media by the )CONTINUE command cannot be loaded into a different 
5110 with a smaller active workspace. 
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The following formula shows how much storage in the active 
workspace is required to perform an input or output operation to tape 
or diskette using an APL shared variable (see Input /Output Control): 

REQUIRED STORAGE = BUFFER + SHARED VARIABLE + 
OVERHEAD 

where: 



• 



REQUIRED STORAGE is the amount of storage that must be 
available in the active workspace (see DWA) before an input or 
output operation to tape or diskette can be performed. If there is 
not enough available storage, a WS FULL error occurs. 

• BUFFER is the amount of storage required by the data assigned to 
the shared variable. This storage is only used during the 
input/output operation. 

• SHARED VARIABLE is the amount of storage required for the data 
assigned to the shared variable. 



• 



OVERHEAD is the amount of storage used when the input/output 
operation is specified. The overhead is as follows: 

OUT and OUTF operations-812 bytes 

IN operation-792 bytes 

INR, lOR, lORH operations-356 bytes 
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ADDITIONAL STORAGE USING DISKETTE DATA FILES 

You can use a direct access data file to store variables that are not 
currently needed in the active workspace. These variables can then be 
removed from the active workspace (to conserve storage) and quickly 
read back into the active workspace as needed. You can use the 
following procedure to store variables for later use on a diskette data 
file: 



1 . Establish a type M direct access data file {see Input /Output 
Control) using dummy records. The first dummy record written 
to the file should require as much diskette storage as the largest 
variable that is to be written to the file. For example, you might 
use the following user-defined function to establish a type M file 
with 256 bytes allocated for each record: 



You must specify the file 
ID enclosed in single quotes. 



vDUMMYi::i:;i:iv 

\? DUMMY ; c ; X ; I ^ 

i::i.::i :i:<e-o 

r.:2::i xm obvo 'c 

i:: 3 ::i c: <•■ x <•■ ' o u r i- ;i. i o o b :i: 1:1 ^== ( r e a i... . s r r a c^ e; ) r y p i:;: ^^ m 

i:m:] ■•KOi^.i.tx<-c) /error 

i:5::i loop:c<"256(:)' a' 

161 KOp^:l.tX^C) /error 

i::7:i -K2o;::]:<-:i:*:i. >/loop 
i::8:] c<-\0 

1:9:1 ->(0?^.1.tX<"C) /ERROR 

i::i.o:i "the data file is created succebbfully • 

i:i:i.:j -m) 

1: 1 2 :i 1;: R R OR:" 1;: R R R - r H E R li: If u R N c D li: ]:$:>: ' , ? x 



Establish a pair of shared variables, and specify direct access 
input/output operations to the data file. For example, you might 
use the following user-defined function: 



i: :i. :i 



2:1 
3:1 
ii::i 
5:1 
6:1 
7:1 
e:i 
9:1 
;i.o 
:i.i 



V 



) 



:i 1; 



vopENi:n:iv 

OPEN fileid;x 

X^I nSVO 2 7 p'CTLSAVEDATSAVE 

•^ ( A / X i^ 2 ) / lii: R R R 

(:rn...8 AVE<- ■ i o r i d==== ( ■ , f i i...E i d , 

X^-CTLSAVE 
••K0i^:l.?X)/ERROR2 

' s u c: E s 8 f u I.. p E R A T" :r. N ■ 
sAVELi$;n> tip* ' 

•M) 
: R R R : ' T l-l E !•• F E R I- A :i: I... E D •■•■ - J l"l E R E B U i... T IB: ' 

;:rror2:"the open failed the return code: 



You must specify the 
file ID enclosed in 
single quotes. 



tX 



•fX 
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3. Store the variable in the data file. For example, you might use the 
following user-defined functions: 

The left argument must be 1 to 

expunge the variable name from 

the active workspace; otherwise, ^ The right argument is the variable 



the left argument must be 0. ^^ name enclosed in single quotes. 




vsAVEi::om 

V EXPUNGE 'SAVE VAR;HABI<;X 

i:: 1 :i .+. ( o ==:=i::inc • sa vel i bt • > / ■ s a vel i bk- o o p 

1:2:] i.( (pSAVEL3:BT>i::l.:]::pVARf-, VAR)/"BAVEL:i:BT^BAVEI..IBT r-JY VAR' 

i: 3 :i .*. ( ^ v/M ASK <•• ( < ( (c>s AVE!... I ST > r :i. ::i t V A R ) a . ::::B A VEL :i: sr > > / ■ s a vfi . i si ^■ 

SAVELIBT BY VAR' 

i:'rj nl<-((:>savel:i:st)i::i.::i 

1:5:3 DATBAVE<".fVAR 

1:: 6 ::i CTLSA viiiS- 1 , < < nl t v a r ) a . ::::s a vel i bd \ i 

1:7:1 -K Op4"7CTLBAVE) /error 

f:8:i x<"0 

1:9:1 aEXPUNGE/'X^-OEX • ' ■ ,VAR, * " ' ' 

i::io:i "the variable ib saved ',(x/"ano expungfd') 
i::i.i:i -M) 

I:12:J ERROR: 'save FAILED" 
V 

VBYi:O^V This function is used 

ri". '^liZi ^^"i^77^ -by the SAVE function. 

L J. J A<"<2t ( pA) , 1 :i. ) pA 

i::2:3 Bf-<2t(pB), i dpb 

1:3:1 ROU<":l.t<pA)rpB 

i::m-:i A<-(Rou/-:i.tpA)tA 

1:5:1 B4"<R0W, ■:l.tpB)tB 

r.6:i z<"A,B 



4. At a later time, read the stored variable back into the active 
workspace. For example, you might use the following 
user-defined function: 

vr ^The right argument is the 

VFETCHi:o:iV ,*/ variable name enclosed 

V Z<"FETCH VAR; MASK ;NL in single quotes, 

i: 1 :i --^ ( ::::|:|NC ' B A VEL I BT ■ ) /NOTFOUND 

i::2:3 ••^( < pvar<", var) >NLf:i. t pbavel:i;bt)/notfound 

1:3:1 ••K''v/MABK*(NLtVAR) A . :=:=SAVELIBT) /NOTFOUND 

U\"\ CTLBAVE<-0,MASKx.1. 

[:5:3 ••K0?^+7CTLBAVE)/0 

C6:3 Z<-VAR, ■ IB~FOUND' 

1:73 AVAR, '^-DATBAVE" 

re:] -^O^DATBAVE^-ro"' 

un NOTFOUNi:iTz^-vAR, • :i:s not found :i:n the fii.f' 

V 
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5. Before the contents of the active workspace can be written to the 
media by the )SAVE command, the input/output operations to the 
data file must be terminated. For example, you might use the 
following user-defined function: 



y CLOSE FILEID- 



You must specify the file I D 
enclosed in single quotes. 



:i.::i ctlsave^-ui 

2::i X<-CTLSAVE 

31 -KOi^ltxy /ERROR 

i\. ::i ' T H E F 1 L E C L S E IJ S U C C E S S E U L, I... Y ' 

5 ::i ■■> 

6::i ERROR: "THE FILE DID NOT CLOSE THE RETURN CODi 

7::i X 



Note: If you want to use the data file at a later time, do not 
terminate the input/output operations. Instead, you should use 
the )CONTINUE command to write the contents of the active 
workspace to the media and then use the )RESUME command to 
reestablish the input/output operations at a later time. 

This procedure works as follows, using the sample user-defined 
functions: 



)HARI< :l.O :l. B :!.:l.- 
MARKED 0008 () I 



File number 8 is used as 
the data file. 



DUMiiY- 



Create the data file 



r !••! i;;: d a if a e 1 1... i;;: i s c; r e. a r i;;: d s u c c e. s s e u l l y used to save the 

variables. 



OPEN ■ REAL.STORAGE'- 
SUCCESSFUL OPERATION 



The data file is ready 

for input/output operations. 



A variable to 
be saved for later 
use. 



NFORHATIONt" * A PROGRAHMING LANGUAGE '' 
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The variable is to be expunged. 
/ 

:i. SAVE • :i:nf(:)rmat:i:dn' 

THE VARIABLE IS SAVED AND EXPUNGED 



INFORMATION 
VALUE ERROR 

INFORMATION 



The variable no longer exists in the 
active workspace. 



FETCH "INFORMATION 
INFORMATION IS FOUND 



INFORMATION 
A P R C) R A M M I N L A N C^ U A G Jr.: 



APL*"'DATA" 



SAVE 'APL' 
THE VARIABLE IS SAVED 



APL 



DATA 



Read the variable back into 
the active workspace. 



The variable is saved, but it is 
not expunged. 



FETCI 
NAME IS NO' 



NAME ' 

OUND IN THE 



A variable not saved in the 
data file. 



FILE 



CLOSE "REAL. STORAGE' 
HE FILE CLOSED SUCCESSFULLY 



'Before the active workspace 
can be saved, the data 
file must be closed. 
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Chapter 5. Console Control 



The 5110 console consists of a keyboard, a display screen, and 
switches. 




In this chapter, the following topics concerning the 5110 console are 
discussed: 

• Controlling the input from the keyboard 

• Controlling the position of the information on the display screen 

• Sounding the audible alarm 

• Console control through a user-defined function 



Console Control 59 



CONTROLLING THE INPUT FROM THE KEYBOARD 

The following illustration shows the positions on the alphameric 
keyboard of the uppercase alphameric characters, the APL symbols, 
the APL keywords, and the special character combinations: 



frLOAD^fTsAVrifl'cONinC > l-'B ) ( ' ^^S J [ I VARS )[ ) COPY ) [ ) WSID )()0UTSEl1( ) MarJTK P J P '^'''' j(DEt-ETgJL!Ngggi) 



COPY 
DISPLAY 



i O I T 1 W J T I E J I R J I T J i Y J I U J I I J ^ 

[ ^^° J [ A J T L_S. J [ D J i F [ G 1 i H J J I K J 

V \/nUA\|/DPW\|/ e \|/ la Al/ <>' \J/ 4 Al/ <>. NJ/ PI A 



9 I I J [ Lj_J L 



MA Al/ A 



o T p 



zr-iit-y 



/ 



/OCR \l/nFx\|/T^\|/nsvrj\l/ ^ \l/ ^ \ 









EXECUTE 



/• 




/Vofe; The special character combinations are engraved on the front of 
the appropriate key on the 5110 keyboard. If the 5110 is a 
combination APL/ BASIC machine, the special APL character 
combinations are below the BASIC keywords. 

When you turn the 5110 power on, the 5110 is in standard APL 
character mode. That is, you enter the uppercase alphabetic 



characters without using the shift 



<2> 




key, the APL symbols 



using the shift key, and the APL keywords and special character 
combinations using the CMD key. For example, if you press: 




|/nuA\| 



The character A is entered from 
the keyboard. 



(JP^ ^ 



The character a is entered from 
the keyboard. 




The character combination DWA 
is entered from the keyboard. 
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You can also enter lowercase alphabetic characters from the keyboard. 
To do this, you use one of the following procedures: 

• Use the keying sequence: 
1. Press the IB key. 



2. Hold down ^^^^ fll^B (shift) key and press the flB (scroll 
down) key. 

Enter the following statement to use the console control (DCC) 
system function: 



A 3 as the left argument specifies that the DCC system 
function is used to change the character mode. 



3 DCC: I 




Specifies lowercase alphabetic characters. (See the 
IBM 51 10 APL Reference Manual, SA2 1-9303, for a 
complete description of the DCC system function.) 

Once the 5110 is in lowercase character mode, you enter the 
lowercase alphabetic characters without using the shift key, the 
uppercase alphabetic characters using the shift key, and APL 
symbols using the CMD key. For example, if you press: 

a The character a is entered from 

thekeyboard. 



The character A is entered from 



iTTi o TPh l^l^^n^ "'"'^® character 

(ji^^^ \/^s\ thekeyboard 




The character a is entered from 
the keyboard. 



You cannot enter the special character combinations using the CMD 
key and a single key when the 5110 is in lowercase character mode. 
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The 5110 remains in lowercase character mode until: 

• The system power is turned off. 

• The RESTART switch is pressed. 

• One of the following procedures is used to change the keyboard 
entry mode to standard APL characters: 

- Perform the keying sequence: 
1. Press the in key. 



2. Hold down theflpH^ (shift) key and press the flB (scroll 

up) key. 
Enter the statement: 

3 OCC 

Specifies standard APL character mode 



CONTROLLING THE INFORMATION ON THE DISPLAY SCREEN 

You can control the information and the position of the information on 
the display screen by using: 

• The scroll up MB and scroll down fl^ keys 

• The DOC (console control) system function to turn display on or off 

• The Dec system function to scroll the information on the display 
screen up or down 

• A pair of shared variables 

You are already familiar with using the scroll up and scroll down keys 
to position the information on the display screen. How to use a pair of 
shared variables to read and write data at any position on the display 
screen is discussed in detail under Input /Output Control. How to use 
the Dec system function to control information on the display is 
discussed in this section. 
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Using the DCC System Function to Control on the Display Screen 

In the previous discussion on controlling the input from the keyboard, 
the DCC function was used to place the 5110 in lowercase alphabetic 
character mode. The DCC function can also be used to: 

• Turn the display screen on or off during the execution of a 
user-defined function. The primary advantage in turning the display 
screen off is that the 5110 internal processing speed is increased by 
approximately 18%. 

• Scroll the information on the display screen up or down. 

To turn the display screen off during the execution of a user-defined 
function, the left argument of the DCC function must be a 1 and the 
right argument must be 0. The display screen remains off until one of 
the following occurs: 

• The user-defined function completes execution. 

• The DCC function Is used to turn the display screen on again (both 
the left and right arguments are specified as 1). 

• A later statement in the user-defined function generates a result to 
be displayed. 

Since the DCC function generates an explicit result, that result must be 
assigned to a variable to prevent the display screen from being 
immediately turned on and the result displayed. For example: 

i:.i.::i m-i ncc o 

When the DCC function is used to scroll the display screen up or 
down, the left argument must be 4 and the right argument specifies 
the number of lines to scroll up or down. For example: 

f^^-M- rice B Scrolls the information on the display screen 

up 8 lines 

R<-M- OCC "3 Scrolls the information on the display screen 

down 3 lines 

In the previous examples, the explicit result of the DCC function is 
assigned to a variable. Otherwise, the explicit result is displayed after 
the DCC function scrolls the display screen up or down. 
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SOUNDING THE AUDIBLE ALARM 

Another use of the DCC function is to sound the audible alarm feature, 
if installed. To do this, the left argument must be a 2 and the right 
argument is: 

• A 1 to sound the audible alarm. The audible alarm remains on until 
any input is entered from the keyboard or the DCC function is used 
to turn the audible alarm off (the right argument is a 0). For 
example: 



R<"2 OCC :l. :l 1 

turns the audible alarm on and off three times. The on/off interval 
is approximately 0.006 second. 

• A vector of 2's, where each 2 sounds the audible alarm for 
approximately 1/4 second. For example: 

\'«-2 i::iCC 2 2 2 2 

sounds the audible alarm four times for approximately 1 /4 second 
each time. 
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CONSOLE CONTROL THROUGH A USER-DEFINED FUNCTION 

The Dec system function, like any other system function, can be 
executed from a user-defined function. This technique allows the 
following console control operations to be initiated from a 
user-defined function: 

• Turn the display screen on or off. 

• Sound the audible alarm. 

• Set the keyboard input to standard APL characters or lowercase 
alphabetic characters. 

• Scroll the display screen up or down. 

• Set the left tab position for printed output (see Printer Control for 
more information on setting the left tab position). 

Following is an example of initiating console control operations from a 
user-defined function: 

'^ CONTROL ; NAHE ; STATEMENT .: R / Set the keyboard Input to lowercase 

ki n 'i !:•!!.:!:.' '''^'"~ ~ y alphabetic character mode. 

-.-....I Hi" A IJLC 1-. / 

3::i 'ENTER YOUR EIRST AND IA91 NAME" 
'1:1 NAMEf-O 

5:1 R<"3 OCC 0- — Set the keyboard input to standard 

7^ ^^^C^. ■ APL Character mode. 

b:i i!h-name 

9::i ■ , ENTER A STATEiiENT TO W EXECUiTEri ' 

:i.o::i R<-ii- occ 2 
i:::i.:i.::i state men t<-o 
1 7"\ Rfi-i- n ("■(■' '•' 

•j 3 ;:i Rf. 1 linJ (j ^ . /Turn the display screen off to improve 



:l.'+:i R^aST ATEMENT internal performance when the next 

15 "I 'THE RESULT IS; '^ v statement Is executed. 



16:3 R 

17:1 R<"2 rice 2 2 2 2 



The display screen is turned on again when 
output Is sent to the display screen. 



Sound the audible alarm when the user-defined 
function has completed execution. 
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Chapter 6. Library Control 



The tape or diskette files where you store information is your library. 
In this chapter, the following topics concerning the 5110 library control 
are discussed: 

• Determining the size of a tape or diskette file 

• Writing data to a tape or diskette file 

• Getting data from a tape or diskette file 

• Controlling files in the library 

• Maintaining data security 

References are made to some of the 5110 system commands; for 
example, the )MARK command or the )RESUME command. See the 
IBM 5110 APL Reference Manual, SA21-9303, for a complete 
description of the system commands. The description includes the 
required syntax for each system command. You must use the proper 
syntax to enter a system command so that the 5110 will accept that 
command. 
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DETERMINING THE SIZE OF A TAPE OR DISKETTE FILE 

Before information can be stored on the media (tape or diskette), the 
media files must be formatted by the )MARK command. When using 
the )MARK command, you can use the following formulas to 
determine the maximum size a file should be marked. The formula for 
a workspace file [the contents of the active workspace were written to 
the storage media with a )SAVE or )CONTINUE command] is MAXSIZE 
= r3 + (CLEAR-ACTIVE) -r- 1024, where: 

• MAXSIZE is the maximum amount of media storage (number of 
1024-byte blocks) that would be required to write the contents of 
the active workspace to the media. 

• CLEAR is the value of DWA in a clear workspace. 



• 



ACTIVE is the value of DWA just before the contents of the active 
workspace are written to the media. 



The formula for a data file (data written to the media using an APL 
shared variable) when all of the data is contained in the active 
workspace is MAXSIZE = f (WITHOUT-WITH) - 1024, where: 

• MAXSIZE is the maximum amount of media storage (number of 
1024-byte blocks) required to write the data to the media. 

• WITH is the value of DWA with the data in the active workspace. 

• WITHOUT is the value of DWA before any data to be written to 
tape or diskette was stored in the active workspace. 

There is no formula for determining what size to mark a data file when 
the data is written to the media as it is entered from the keyboard. 
The amount of storage required depends upon how much data is 
entered from the keyboard and what type of data is used. For 
information on how many bytes of storage are required by the various 
types of data, see Storage Cons/derations in the Active Workspace 
Control chapter. 
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WRITING DATA TO A TAPE OR DISKETTE FILE 

You can write data to a file by using the )SAVE command, the 
)CONTINUE command, or an APL shared variable. The )SAVE or 
)CONTINUE commands are used to write the contents of the 5110 
active workspace to a file. An APL shared variable is used to write 
individual data records to a data file (shared variables are discussed in 
detail under Input/Output Control). 

The following list shows the advantages and disadvantages of using 
the )SAVE command versus the )CONTINUE command. You should 
consider these advantages and disadvantages when choosing which 
command you are going to use when writing the contents of the 
active workspace to the media. 



Using the )SAVE Command 

Advantages: 

• The stored workspace can be loaded into a 5110 that has a smaller 
active workspace than the original active workspace, providing the 
stored workspace does not require more storage than is available in 
the smaller active workspace. 

• The additional storage is available to the user when the stored 
workspace is loaded into a 5110 that has a larger active workspace 
than the original active workspace. 

• The symbol table is cleared of unused or expunged symbol 
references. 

• The )COPY and )PCOPY commands can be used to copy specified 
variables or user-defined functions from the stored workspace. 

Disadvantages: 

• The active workspace is not written to the media as fast as when 
the )CONTINUE command is used. 

• The stored workspace is not loaded into the active workspace as 
fast as when the )CONTINUE command is used to write the 
workspace to the media. 

• If the active workspace contains suspended functions or open data 
files exist, the active workspace cannot be written to the media. 
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Using the )CONTINUE Command 

Advantages: 

© Even if the active workspace contains suspended functions or open 
data files exist, the active workspace can be written to the media. 
Any open data files or suspended functions can be restored by the 
)RESUME command. The )RESUME command is discussed in more 
detail under Getting Data from a Tape or Diskette File in this 
section. 

© The active workspace is written to the media faster than when the 
)SAVE command is used. 

© The stored workspace is loaded into the active workspace faster 
than when the )SAVE command is used to write the workspace to 
the media. 

Disadvantages: 

• The )COPY and )PCOPY command cannot be used to copy variables 
or user-defined functions from the stored workspace. 

• The stored workspace can only be loaded into a 5110 with an active 
workspace at least as large as the original active workspace. 

• The additional storage is not available to the user when the stored 
workspace is loaded into a 5110 that has a larger active workspace 
than the original active workspace. 
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GETTING INFORMATION FROM A TAPE OR DISKETTE FILE 

You can read information from a tape or disicette file by using the 
)LOAD, )RESUME, )COPY, )PCOPY commands, or an APL shared 
variable. The )LOAD, JCOPY, )PCOPY, and )RESUME commands are 
used to place the contents of a stored workspace into the 5110 active 
workspace. An APL shared variable is used to read individual data 
records from a data file (shared variables are discussed in detail under 
Input/Output Control). 

Generally, you use the ) LOAD command to replace the contents of the 
active workspace with the contents of a stored workspace. However, 
if there were shared variables or suspended functions in the active 
workspace and the )CONTINUE command was used to write the active 
workspace to the media, the )RESUME command reads the stored 
workspace into the active workspace and reestablishes the shared 
variables and/or suspended functions. That is, the system 
environment is reestablished as it was when the )CONTINUE command 
was issued. 

Using the )CONTINUE and )RESUME commands allows you to work 
with shared variables or suspended functions, write the active 
workspace to the media, and then reestablish the system environment 
at a later time so that you can continue working with the shared 
variables and/or suspended functions. See The jRESUME Command 
in the IBM 5110 APL Reference Manual, SA21-9303, for a description 
of how the shared variables are reestablished. 

If a workspace was stored on the media using the )SAVE command, 
you can copy all or part of that workspace into the active workspace 
by using the )COPY or )PCOPY commands. The )COPY command 
copies all or specified objects (variables or user-defined functions) into 
the active workspace and replaces any objects in the active workspace 
that have the same name. The )PCOPY command copies all or 
specified objects into the active workspace; however, any objects in 
the active workspace that have the same name are not replaced (they 
are protected). The )COPY and )PCOPY commands allow you to read 
more than one stored workspace or parts of more than one stored 
workspace into the active workspace without replacing objects already 
existing in the active workspace. 
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CONTROLLING THE FILES IN THE LIBRARY 

Once you have stored several workspace and data files on a tape or 
diskette (your library), you might want to know what files you have in 
your library. You can use the )LIB command to display the file headers 
for a specified tape or diskette. The file headers provide you with 
such information as the file number, the file ID, the file type, and so 
on. See The )UB Command in the IBM 5110 APL Reference Manual, 
SA21-9303, for a description of the information contained in the file 
header. 

When there are files on tape or diskette that contain data that is no 
longer required, you can mark these files unused by issuing the )DROP 
command. Once a file is marked unused, any data in the file can no 
longer be read into the 5110 and the file is available for other uses. 

Also, if a diskette file is no longer required, you can make the file 
space available for reallocation by issuing the )FREE command. This 
allows the file space on the diskette to be used for other numbered 
files by the )MARK command. See Diskette Concepts for more 
information on how files are allocated on a diskette. 
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DATA SECURITY 

You are primarily responsible for the security of any sensitive data. 
After you are through using the 5110, you can remove the data in the 
active workspace by one of the following: 

• Using the )CLEAR command to clear the active workspace 

• Pressing the RESTART switch 

• Turning the POWER ON/OFF switch to off 

There are several methods available for protecting or removing 
sensitive data on a tape or diskette. These methods are: 

• Assigning a password to the workspace when the system is writing 
the active workspace on the media. 

• Rewriting a file, which makes the old data inaccessible. 

• Filling a data file with meaningless data. For example, the following 
user-defined function fills file 4, a data file named DATA on tape 1, 
with zeros: 

?SECUR:rrY;A;B 
::i.:i :i. osvo 'A* 
:2::i a^-'out ioom- :n:i===:<DATA) ■ 
:3:i Bi-ii) looopo 
:m:i ur: a<-b 
5:;i ••KAi::j.3==M))/yR? 

• Setting the tape cartridge SAFE switch in the SAFE position to 
prevent someone from accidently writing on the tape. 

• Using the )PROTECT command to prevent someone from accidently 
writing on a diskette file. 

• Using the )VOLID command to prevent unauthorized access to the 
diskette files. 

• Storing the tape or diskette in a secure place. 
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Chapter 7. Tape Concepts 



There are 204K bytes (IK = 1024 bytes) of tape storage available on 
an IBM Data Cartridge. This tape storage is used for file headers, 
workspace files, and data files. In this section, the following topics are 
discussed: 

• How to fornnat the tape 

• How to determine the amount of storage on a tape cartridge that is 
actually available to you 



FORMATTING THE TAPE 

You must use the )MARK command to format files on the tape before 
you can store the contents of the active workspace or data records on 
the tape. For example: 



)MARI< 



5 1. 



Starting File Number 

^Number of Files to Mark 

Size of the Files In Increments of 1,024 (IK) 
Bytes. In this case, the size of the marked 
files is 10, 240 (10 x 1,024) bytes. 

Once the previous )MARK command is successfully completed by the 
5110, the tape is formatted as follows: 



This hole indicates 
the beginning of 
the tape storage. 



File Headers 



This file header 
indicates end of 
marked tape. 




Each file contains 
10,240 bytes of 
storage. 



Unformatted 
Tape 



Tape Concepts 75 



The file headers contain information about the file, such as the file 
number, file name, file type, and so on. Each file header requires 512 
bytes of tape storage. 

Now, if you want to format additional files on the tape, you must use 
the )MARK command again. For example: 



)MARK 20 



Starting File. Remember, in this 
example, five files are already 
formatted. 



Number of Files to Mark 



■File Size 



The tape is now formatted as follows: 

File 6 Header 




6 



File 6 is formatted 
after file 5. 



Unformatted 
Tape 



When the information in a tape file is no longer needed, you can use 
the )DROP command to mark the file unused so that the file is 
available for other uses. However, once a file is formatted, you 
cannot increase the size of the file without re-marking the file. When 
you re-mark an existing file, any information in the files following the 
re-marked file is lost. For example, assume you want to increase the 
size of file 4 on the tape from 10K to 15K: 



I 




\ 



You want to increase the size 
of file 4 by 5K. 
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After the command: 



)MARI< 



File Size 

Number of Files to Format 
Starting File Number 

/ 




is successfully completed, the tape is formatted as follows: 



zZA 



/A 



V77 



(A 



7^ 



File 4 now contains 

15K bytes of tape storage. 



This file header now indicates the end of 
the marked tape, and any data following 
this file header is lost. 



A formatted tape has the following characteristics: 

• The files are of variable length from 1 K to 200K, in 1 K increments. 

• The files can be randomly accessed; that is, you can read a file 
without having to read the previous file. However, the data in the 
files must be accessed sequentially. 

• It can contain both workspace and data files. 

• It can contain both APL and BASIC files. 



Tape Concepts 77 



DETERMINING THE AMOUNT OF STORAGE AVAILABLE ON A TAPE 
CARTRIDGE 

There are approximately 204K bytes of storage on each tape cartridge, 
but the amount of tape storage actually available to you depends on: 

• How many files are marked (formatted) on the tape 



• How the data files were written to tape 

Each file on a tape cartridge requires one 512-byte file header. 
Therefore, as you mark more files on a tape cartridge, more tape 
storage is used for file headers. For example, if you mark one 3K file 
on a tape, 512 bytes of tape storage are used for the file header. 
However, if you mark three IK files on tape, 1,536 bytes of tape 
storage are required for the file headers. 

One 3K File 



0.5K 



3K 



Three IK Files 



0.5K 



IK 



0.5K 



IK 



0.5K 



IK 



Notice that, in each case, a total of 3K bytes of tape storage is 
allocated for tape files. However, in the second case, an additional 1 K 
bytes more of tape storage are used. 

The amount of data you can store in a data file depends on how the 
data is written to the data file. (See Input /Output Control for a 
complete description of writing data to data files.) For example, when 
you first write data to a data file (an OUT operation), the individual 
records are sequentially written to tape starting at the beginning of the 
data file. Once these records are written to tape, the data file might 
look like this: 



Data File 



■Data Records 



\ 



Beginning of the 
Data File 



Last Data Record 



/ 

Unused 
Tape Storage 




/ 

End of the 
Data File 
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Now, assume you add data to the data file at a later time (an ADD 
operation). The new data starts at the first 51 2-byte boundary after 
the last record in the data file. The tape storage between the last data 
record and the additional data records is unavailable for use. Once the 
new data records are written to tape, the data file might look like this: 



Data File 



Data Records 



/ 



512-Byte Boundaries (tape storage is 
divided into 51 2-byte segments) 



'A 



Additional Data 




\ 



Beginning of 
the Data File 



/ 



Unavailable 
Tape Storage 



Last Data Record 



/ 

Unused 
Tape Storage 



As you add more data to the file, it is possible for more tape storage 
to become unavailable. You can compress the data in the data file (use 
the unavailable storage) by first reading all the data records from the 
file and then writing the data records back to the file, starting at the 
beginning of the data file (an OUT operation). 
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Chapter 8. Diskette Concepts 



The IBM diskette is a thin, flexible disk permanently enclosed in a 
semirigid, protective, plastic jacket. When the diskette is properly 
inserted in the diskette drive, the disk turns freely within the jacket. 
The diskette is inserted in the diskette drive as follows: 




This label must be in the 
lower corner as the diskette 
is inserted in the diskette drive. 
The diskette drive door must be 
closed and latched after the 
diskette is inserted. 



Data is written on the diskette at specific locations (addresses) by the 
system. These addresses provide direct access to specific 
information. Data written at an address remains there until it has been 
replaced by new data. To read data, the desired address is found and 
the data is read into the 5110. 

Before being shipped to a user, each IBM-supplied diskette is 
initialized. Initialization is a process whereby label information and data 
addresses are recorded on the diskette. In this chapter, the following 
topics are discussed: 

• Diskette wear 

• Diskette addressing and layout 

• Diskette types and formats 

• Diskette initialization 
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« Diskette volume ID, owner ID, and access-protect indicator 

« Diskette file information, such as file ID, write-protect indicator, and 
organization 

« Reallocation of diskette file space 

o Amount of storage available on a diskette 

DISKETTE WEAR 

The use of flexible diskette storage provides some significant 
advantages, such as low cost, compact size, multiple system functions, 
and ease of media handling and storage. It should be recognized, 
however, that during recording and reading, the read/write head is in 
contact with the media, causing diskette wear over time. Variations in 
the rate of wear will depend on the particular operating environment 
and application characteristics. Care in the storage, use, and handling 
can also affect diskette life. (See guidelines in the IBM 5110 APL 
Reference Maual.) Excessive wear, handling, or contamination can 
cause possible failures in recording and/or reading. 

Ultimate wear is to some extent dependent upon total usage of 
individual tracks. Care taken to distribute data so that accessing 
occurs over the entire recording surface with about the same 
frequency can extend the useful life of the diskette. Actual experience 
with individual applications and environments will allow development 
of guidelines as to when the media should be replaced. 

Unpredictable circumstances such as contamination or severe handling 
can cause an early error to occur. 

For the previous reasons, consideration should be given to providing 
an adequate recovery plan, such as: 

• Backing up critical programs and data files on a second diskette for 
use in the event of an error on the primary diskette. 

• Periodically moving frequently used files to alternate locations on 
the diskette (see the copy function in the IBM 5110 Customer 
Support Functions Reference Manual). 
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DISKETTE ADDRESSING AND LAYOUT 

A diskette address consists of a combination of cylinder number, head 
number, and record number as follows: 



CC H RR 



Record (sector) Number. The sector into which the data 

is to be written or from which the data is to be read. 

Head Number. The side of the diskette on which the data is to 
be written or from which it is to be read. This number is hex 
for all one-sided diskettes and for side of two-sided diskettes. 
The number is hex 1 for side 1 of two-sided diskettes. 



■ Cylinder Number. This number identifies the cylinder onto which a 
physical record is written or from which it is read. 



Track and Cylinder 

A track is the recording area on a single diskette that passes the 
read/write head while the disk makes a complete revolution. The 
read/write head is held by a carriage that can be moved to 77 distinct 
locations along a straight line from the center of the disk. Therefore, 
each diskette has 77 concentric tracks on which data can be stored. 



01 



o 
i: 



77 Tracks 



The diskette drive for two-sided diskettes has a read/write head on 
each side. Each track on side of a two-sided diskette has an 
associated track on side 1 . 

A cylinder is one track On a one-sided diskette or a pair of associated 
tracks (the corresponding tracks on opposite sides of the diskette) on 
a two-sided diskette. There are 77 cylinders (numbered to 76) on a 
diskette. 
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Sector 



A sector is a portion of a cylinder. All sectors on a single cylinder are 
the same size, and the number of sectors on a cylinder depends on 
the number of bytes per sector (see Diskette Types and Formats in 
this chapter). 




Track 00 



One Sector 



Index Cylinder 

Cylinder is called the index cylinder and is reserved for information 
describing the diskette and its contents. It contains information about 
the diskette, such as volume and owner identification. The index 
cylinder also contains information associated with each file on the 
diskette. This includes the name of each file and the addresses 
associated with the file extents. An extent is the maximum space a file 
can occupy. The address at the beginning of this space is called the 
beginning of extent (BOE). The address at the end of this space is 
called the end of extent (EOE). A file may not use all of the space 
allocated for it by the BOE and EOE addresses; therefore, another 
address for end of data (EOD) exists. 

Actual space being used for data 



BOE 



EOD 
I 



EOE 



Area allocated for the file (extent) 



The EOD address is used to identify the next unused area within the 
extent or to indicate that data has been written to the EOE address. 
(See the diskette initialization function in the IBM 51 10 Customer 
Support Functions Reference Manua/, SA21-9311, for a complete 
description of the index cylinder.) 
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Alternate Cylinders 

The last two cylinders (75 and 76) are reserved for use as 
replacements (alternate cylinders) for defective cylinders. The 
remaining cylinders (1 through 74) are used for storing data. 



DISKETTE TYPES AND FORMATS 

The 5110 uses three types of diskettes; the one-sided diskette (1), 
with data recorded on just one side; the two-sided diskette (2), with 
data recorded on both sides; and the two-sided diskette (2D), with 
data recorded on both sides at double density. The diskettes are 
initialized (see Disk Initialization) into various formats consisting of: 

• The number of sectors per cylinder 

• The number of bytes per sector 
The possible diskette formats are: 





Sectors 


Sectors 


Bytes 




per 


per 


per 




Track 


Cylinder 


Sector 




^26 


26 


128 


Diskette 1 


15 


15 


256 




^ 8 


8 


512 




"26 


52 


128 


Diskette 2 


15 


30 


256 




^8 


16 


512 




"26 


52 


256 


Diskette 2D 


15 


30 


512 




^8 


16 


1,024 



Note: The diskette types (1, 2, or 2D) are identified on the diskette 
label, and the )VOLID command can be used to determine the bytes 
per sector (record size). 
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DISKETTE INITIALIZATION 

The diskettes must be initialized before they can be used for storing 
data. All IBM-supplied diskettes are initialized before they are shipped 
to a customer. Reinitializing is not required unless: 

• The diskette was exposed to a strong magnetic field. 

• A defect occurred in one or two cylinders. In this case, initialization 
can be used to take the bad cylinder{s) out of service and use one 
or two of the alternate cylinders. 

• A sector sequence other than the sequence existing on the diskette 
is desired. 

• A format (number of sectors per cylinder) other than the existing 
format is desired. 

See the IBM 5110 Customer Support Functions Reference Manual, 
SA21-9311, for a description of the diskette initialization function. 



VOLUME ID, OWNER ID, AND ACCESS PROTECTION 

Each initialized diskette has volume ID, owner ID, and an 
access-protect indicator. The volume ID is the identification of the 
diskette volume, and the owner ID is the identification of the diskette 
volume owner. The access-protect indicator is used to prevent 
unauthorized access (reading and writing) to the diskette volume. 

The )VOLID command is used to display or change the volume ID and 
owner ID or to change the access-protect indicator. 
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FILE ID 



Each file header on a formatted (marked) diskette has a file ID 
(identification). When the diskette files are formatted, a file ID is 
automatically generated, even though the files are unused. For 
example, the file name for file 1 is SYS0001 . 

The )FILEID command can be used to display or change a file ID. 

The file ID for a stored workspace must be a simple name. A simple 
name must begin with an alphabetic character and can be up to eight 
alphameric characters. For example: 

SALES200 

The file ID for a data file can be a simple or complex name. A 
complex name is two or more simple names with each name 
separated by a period. A complex name cannot exceed 17 characters 
including the period. For example: 

SALES200.DATA 

SALES.DATA.DIST12 



DISKETTE FILE WRITE PROTECT 

Each file header contains a write-protect indicator. When the 
write-protect indicator is on, no data can be written to the file. The 
) PROTECT command invokes or removes the write-protect indicator 
for a diskette file. 
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DISKETTE FILE ORGANIZATION 

You use the )MARK command to format files on the diskette before 
you can store workspaces or data records on the diskette. For 
example: 



)HARK :l.0 



L 



Diskette Drive 1 



■Starting File Number 



■Number of Files to Format 



■ Size of the Files in Increments of 1 ,024 (1 K) Bytes. In this case, 
the size of the marked files is 10,240 ( 10 x 1,024) bytes. 



Unlike tape files, the diskette files are not always formatted 
sequentially on the diskette. For example, file 2 might be on cylinder 
3, file 3 on cylinder 9, and file 4 on cylinder 7. You can control the 
location of a file on the diskette only by using a totally unmarked 
diskette and issuing )IVIARK commands in the same order as the files 
are to be formatted on the diskette. 

When the information in a diskette file is no longer needed, you can 
use the )DROP command to mark the file unused so that the file is 
available for other uses. However, once a file is formatted, you cannot 
increase the size of the file without re-marking the file. Reallocating 
diskette file space is discussed next. 
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REALLOCATING DISKETTE FILE SPACE 

Unlike tape files, when you i-e-mark an existing diskette file, no other 
diskette files are affected. When you re-mark a diskette file to 
increase the size, the file space presently allocated to that diskette file 
is made available for other files being marked. The remarked file will 
then be located on the diskette where there is enough continuous 
storage available for that file. For example, assume you want to 
increase the size of file 4 from 10K to 15K by issuing a )MARK 15 14 
11 command: 

Disk 
Cylinder 



5 



After you issue the )MARK command 
this file space is no longer allocated 
for File 4. 

Once the file space previously occupied by file 4 is available, that file 
space will be used by a subsequent )MARK command that marks a file 
of 10K or smaller. 

After the )MARK command is successfully completed, file 4 is 
formatted on the diskette at a location where at least 15K of 
continuous storage is available. 



Diskette 
Cylinder 



Another 
Diskette 
Cylinder 



\ 



I 



Unallocated Diskette Storage 

/ 



10 



20K of unallocated diskette storage was 
available at this location before the 
)MARK command was issued. 
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AMOUNT OF STORAGE AVAILABLE ON A DISKETTE 

The amount of storage available on a diskette depends upon: 

• Whether data can be recorded on just one side or on both sides of 
the diskette 

• The number of sectors per cylinder 

• The number of bytes per sector 

Each diskette has 77 cylinders. Cylinder is the index track and is 
reserved for information (file headers) about the diskette files. 
Cylinders 75 and 76 are alternate cylinders that are used as 
replacements for bad cylinders. This leaves cylinders 1 through 74 
available for data storage. The following chart shows the amount of 
storage available with the different types of diskettes: 





Sectors 


Bytes 


Available 




per 


per 


Storage in Bytes 




Cylinder 


Sector 


(cylinders 1-74) 




26 


128 


246,272 


Diskette 1 


15 


256 


284,160 




8 


512 


303,104 




52 


128 


492,544 


Diskette 2 


30 


256 


568,320 




16 


512 


606,208 




52 


256 


985,088 


Diskette 2D 


30 


512 


1,136,640 




16 


1,024 


1,212,416 



Although the previous chart shows the maximum amount of diskette 
storage, the amount of diskette storage actually available to you 
depends on: 

• The number of files and the size of the files marked on the diskette 
» The types of data files that are written to the diskette 

• The allocation of file space as the result of previous )MARK and 
)FREE commands 
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Number and Size of Diskette Files 

The diskette volume/owner identification (7 sectors) and file header 
information are contained on the index cylinder. The remaining 
cylinders on each type of diskette can have the following maximum 
number of files: 



Diskette 1 Diskette 2 Diskette 2D 

Maximum Number 

of Files 19 45 71 



Note: For a type 2D diskette, see the disk initialization function in the 
IBM 5110 Customer Support Functions Reference Manual, SA21-931 1 
for information on how to get additional file headers. 

If you mark the maximum number of files without using all the 
available file space, the remaining file space becomes unavailable for 
storing data. For example, assume you have an unmarked Diskette 1 
with 128 bytes per sector. This diskette has 246,272 bytes available 
for storing data; however, you issue the following command: 



)iiARK :l.O 1.9 



I 

' In this example, diskette drive 1 is used. 



■The starting file number. 



— The number of files to be marked. 



■The size of each file to be marked. 



This command marks the diskette with the maximum 19 files. Because 
each file is 10K bytes, a maximum of 190K (194,560) bytes of storage 
is allocated for the files. Now, if you subtract the allocated diskette 
storage from the available diskette file space: 



246,272 
-194,560 



' For this example, this much diskette storage is 

unavailable for you to store data. 



Types of Data Files 

How to generate the various types of diskette data files is discussed 
under Input/Output Control. Two types of data files can cause 
diskette file storage to be unavailable for storing data: U (unblocked) 
and M (mixed). 
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Type U Data File 

A type U data file specifies that each record in the file starts at the 
beginning of a sector and that a record cannot span from one sector 
to another. 



Data File 



Individual Sectors 



For a type U data file, each record 
must be contained in one sector. 



I 



The sectors on a diskette can be 128, 256, 512, or 1,024 bytes. If a 
record does not require the number of bytes available in a sector, the 
remaining portion of the sector is unavailable for data storage. 



Beginning of 256-Byte Sectors 



Data File 




Unavailable Diskette Storage 

To obtain the maximum available storage for a type U data file, you 
should do one of the following: 

• Write records to the file that are the same size as (or as close as 
possible to) the sector size. 

• Use a diskette whose sectors are initialized (128, 256, 512, or 1,024) 
nearest to the record size. Remember, the entire record must fit in 
one sector. 
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Type M Data File 

A type M data file specifies that each record in the file requires the 
same amount of file storage as the first record written to the file. That 
is, the first record determines the characteristics of the file. Any 
record written after the first record cannot be larger than the first 
record. 

Data File 

^^Beginning of the Data File 



100 Bytes 



100 Bytes 



100 Bytes 



100 Bytes 



100 Bytes 



I 



\ 



The first record used this amount of storage; 
therefore, any following records are allocated 
the same amount of file storage. 

If any of the following records do not require as much storage as the 
first record, the remaining portion of the storage allocated for the 
record is unavailable for data storage. 

Increments of 100 bytes as specified by the first 
record written to the file 




The first record 
written to the file 



Unavailable Diskette Storage 



To obtain maximum available storage for a type M data file, you 
should make the records as uniform in size as possible. Remember, 
the size of the records following the first record must be equal to or 
less than the size of the first record. 
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Allocation of File Space 

Previously in this section, reallocating diskette file space using the 
)FREE and )MARK commands was discussed (see Reallocating 
Diskette File Space). Using the )FREE and )MARK commands to 
reallocate diskette file space can cause fragmented blocks of 
unallocated file space on the diskette. For example, assume a diskette 
has all the file space allocated, except the following 15K of file space 
on a cylinder: 



Diskette 
Cylinder 














y 


V— j "' 




17 


W/. 


'\ 


V— ' 




/ 

10K of Unallocated 
File Space 




/ 

5K of Unallocated 
File Space 



Now, if you need that 15K of storage for a new file to be marked, the 
storage is not available because it is not in 15K continuous bytes. 

The fragmented blocks of unallocated file space can be made available 
by the compress function (see the IBM 5110 Customer Support 
Functions Reference Manual, SA21-9311). The compress function 
closes the gaps caused by the unallocated file space and places all of 
the unallocated file space in one continuous area. 
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Chapter 9. Printer Control 



You can specify what data is sent to the printer by using the )OUTSEL 
system command or an APL shared variable. Also, at any time, you 
can print all the information on th e display screen by holding down the 
CMD key and pressing the j + 1 key. When an APL shared variable 

is us ed to send data to the printer, except for using the CMD 
and r + 1 key, all the data to be printed must be assigned to 

the shared variable. (See Input /Output Control for more information 
on using shared variables for printing data.) The )OUTSEL command 
has three options to specify which data on the display screen is 
printed. These options are: 

• ALL-specifies that all subsequent information displayed is printed. 

• OUT-specifies that only output is printed. Even though input is 
displayed it is not printed. For example: 

8 



If you enter this statement, the statement 

is displayed but not printed. 

.The output (result) from the statement is displayed 
and printed. 



• OFF-specifies that none of the information displayed is printed, 
unless an APL shared variable is used to send the data to the 
printer. 

You can use the following system variable and APL function to specify 
the format of printed output: 

• DPP Specifies the printing precision of numeric data (how many 

digits are printed) 

• 5 Dec n Specifies the starting print position (tab n) from the left 

margin 

• ^ Formats numeric data Into character data 
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FORMATTING OUTPUT 

You can use the DPP system variable to specify the number of digits 
to be displayed and printed for decimal numbers and for integers with 
more than 10 digits. In a clear workspace, the DPP system variable is 
set to 5 (default value). For example: 



:l.23M-l:i.67 



A decimal number with seven digits. 



123M-6 



Only five digits are displayed, and the least significant 
digit is rounded off. 



The value of DPP does not affect the internal precision of the system. 
For example: 



A^-123M-5 . 67 

A 
:l.23ih6 

OPpf-7^ 

A 
1.23M-5.67-. 



npp^-2 

A 



1. .2EM-^ 



■ Only five digits are printed. 
Change the printing precision to seven digits. 
-Notice that the value of A is still seven digits. 



Even though only two digits are printed, the 
internal value of A in the system is seven digits. 



Although the DPP system variable allows you to specify the number of 
significant digits printed for decimal numbers or integers with more 
than 10 digits, there might be times when even more control is needed 
for the printed output. The ^ (format) function allows you to 
specify the precision and spacing of numeric data. The ^ function 
also converts the numeric data to character data. This makes it easier 
to print the formatted numeric data with other character data. For 
example: 



'the clabb average 
d(3Ha:i:n error 

•THE (:;LASS AVERAGE 



BO 



BO 



Numeric Value 



■You cannot join numeric 
and character data 



■THE {::labb average :i:b 

THE CLASB AVERAGE IB; BO 

t 

The Printed Result 



■ ,tBO 



■The Format Function 
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The following examples show how the j function can be used to 
control spacing and precision of numeric data (see the IBM 5110 APL 
Reference Manual, SA21-9303, for a complete description of 
the T function): 

B^-3 2p:l.2.3i|- "•3M-.567 1 2 •■.26 ■:l.23 . M^ 
B 
:l.2.3M- 

i. 2 I-* Numeric Value of B 



0.26 



■•■3i|-.!vi67n 

12 
123.II-5 J 



Z 



Spacing of Nine Positions for Each Number 



Q 't'^ri ^^'''^ number should contain two decimal places 

1.2.31+ "^M-.S?^ 

. :l. 2 , -• Formatted Character Result 

"•.26 •••:I.23*I-I-I5 



Spacing and Precision for the First Column 



/~ Spacing and Precision for the Second Column 

'6 2"9 :I.^B 

:l.2.3i|- •3M-.6^ 

. :l.2 . |-« Formatted Character Result 

•■".26 •••1.23.M- 







\ \ i 



Nine Positions 



Six positions 

You can use the DCC (console control) system function to specify a 
tab position from the left margin. The printed output then starts from 
that tab position. To specify the tab position, the left argument of the 
DCC function is 5 and the right argument specifies the tab position. 
For example: 

■ pr:i:nth;:)::i output' 

PRINTE)Ii OUTPUT /The explicit result of 



!5 OCC 20 



the DCC function. 
1 

■pr:i:nted output* 
printed output 

J 



20 character positions 
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FORMATTING REPORTS 

Sometimes the data stored in the 5110 cannot be used unless the data 
is in a printed report. And the printed report cannot be used unless 
the report is in a readable format. The following procedure can be 
used to generate a readable report, assuming the necessary data for 
the report is already stored in the 5110: 

1 . Determine the headings for the report. The headings should 
describe the information in the report. 

2. Arrange the data so that the data will be located under the 
appropriate heading. 

3. Edit the data (see Useful APL Statements and User-Defined 
Functions for Formatting Reports). 

4. Print the data. 

The following example shows how this procedure might be used. 

Assume you have the following data stored in the system: 

P(S| R J A numeric matrix with each row representing 

392M- 01 a part number of items in stock 

3921102 
392M-03 
392t|-0M- 
392M-05 
392M06 
392M.07 



VI A wp „, A character matrix with each row representing 

qpnr-y the name of the associated part number in 

1.1 IV- matrix PART 

UASHER 

CONTACT 

LEAD 

POST 

CRT 



9 9 9 2 9 Of DATA-. A numeric matrix that 

10 .02 1000 contains the in-stock quantity, 

10 .0 1 1 on-order quantity, cost per 

'5000 2000 ,01 200 part, and reorder quantity for 

, 5 2 the associated part number 

2 50 1 . 3 5 in matrix PART 

"l-OO 2.72 500 

50 20 136.59 20 
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Now, suppose you want a part inventory report that shows: 

• The part number arid name. 

• The in-stock and on-order quantities. 

• The cost per part. 

• The reorder quantity and reorder flag. The reorder flag indicates 
that the combined in-stock and on-order quantities are less than the 
reorder quantity. 

The first step is to determine the headings for the report. In this 
example, the following heading is entered: 

Position 1 on Line 1 



HE-AD<-2 56 p 'PART 
RDER' , 'NUHBER NAME 



QUANTITY COST REC) 
IN-STOCK ON-ORDER PER PART QTY FLAG* 



The second step is to arrange the data so that it is located under the 
appropriate heading. In this example, the following statements are 
used to arrange the data: 



BOBYi- (6 T PART ) , ' ' , NAME- 

BODYfBODY.S /? 0,12 2 8 yDATA 



Join the part numbers and names 
together. 



This matrix now contains the 
part number, name, in-^stock 
quantity, on-order quantity, 
cost per part, and reorder 
quantity for each part on 
inventory. 



The spacing and precision to format each 
associated column of the matrix DATA. 
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At this point there is not enough information available to complete the 
report. The reorder flag is needed to indicate the parts with a 
combined in-stock and on-order quantity that is less than the reorder 
quantity. The following user-defined function might be used to place 
asterisks {*) in the reorder flag column when the in-stock plus 
on-order quantity is less than the reorder quantity: 



i:: 1 1 
1:2:1 
1:33 
i:m-:i 

151 



V 



V 



VRE0RDERFLAGC:n3V 

RF>REGRDERFLAG;:i:;X 

I<"(DATAi: ; 13+DATAi: ; 23 ) -.DATAi: ; >l-J 

XMCltpDATA) 

T i" I /X -I -Selects the rows where the condition 

RF<- ( < 1 1 pDATA ) , 5 ) P ■ ' specified in statement 1 is true 

RFi:i;:3<-'w 



\ 



Places the reorder flag (*****) in the appropriate rows 



Now, the following statement can be used to add the reorder flag the 
report data: 

BODY<"BODY , REORDERFLAG 

The body of the report now looks like this: 
BODY 



3921101 


<3CREW 


1000 







.02 


10 


392M-02 


NUT 


1000 







.01 


1000 


3924- 03 


UASHER 


5000 


2000 




.01 


2000 


392M-0M- 


CONTACT 










.50 


20 0«««ww 


392M05 


LEAD 


20 


500 


t 


.03 


50 


392M.06 


POST 


MOO 








. 72 


50 0««»^* 


392»+07 


CRT 


50 


20 


136 


.59 


200 



The third step is to edit the data, 
placed before each cost per part. 

B0i:iYi::;36:i<-'*' 



In this example, a dollar ($) is to be 



100 



The fourth step is to print the report. This might be done several 
ways; for example: 

• Join the heading and the body and then print the entire report. 

REPDRT^HEACCliJBODY 

• Use a user-defined function to print out the report. For example: 





7REP0RTCCPV 




V REPORT™ 


C:U 


HEAlii" 


121 


B0liY<-<6 tPART), ■ ' ,NAME 


iz:\ 


BDDY<"BODY, 8 9 12 2 8 


m:\ 


BODY<-BOi:iY , REORDERFLAG 


V5:\ 


B0DYC;363<-'*' 


161 


BODY 



fDATA 



V 
Now, when the report is printed, it looks like this: 



REPORT 












PART 


QUANTITY 




COST 


REORDER 


NUMBER NAME 


IN-STOCK 


ON-ORDER 


PER PART 


QTY FLAG 


392M01 SCREy 


1000 





$ 


.02 


1000 


392M-02 NUT 


1000 





$ 


.01 


1000 


392M-03 UASHER 


5000 


2000 


* 


.01 


2000 


392«+0M- CONTACT 








* 


.50 


20 0^t»)t«x 


392«-l-05 LEAD 


20 


500 


* 


1.03 


500 


3921+06 POST 


«+0 





$ 


2 . 72 


500*t^»w* 


3921+07 CRT 


500 


20 


* 


136.59 


200 
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USEFUL APL STATEMENTS AND USER-DEFINED FUNCTIONS FOR 
FORMATTING REPORTS 

Following are examples of APL statements and user-defined functions 
that might be useful for formatting reports. 



Drop Blanks from a Character Vector: 

VDROPLrpV 
S? Z<-DROP X 

X<"'A B C D E FG" 
DROP X 
ABCDEFG 

Drop Blanks and Periods from a Character Vector: 

yi:iROPBPi:i::i:iv 

V Z<-DROPBP X 
111 Z<"('vX€' . ' )/X 

V 

X<"'A.B.C D E F' 
DROPBP X 
ABCDEF 

Replace Periods with Commas in a Character Vector: 

V RE PLACE i::i:]:jv 

V Z<"REPLACE X 

i:i:i xi:(x=-=:' . ' y/xpxn-' , ' 
1:2:3 z^x 

X 
A.B.C D E F 

REPLACE X 
A,B,C B E F 

Drop Leading Blanks in a Character Vector: 

VLEADINCninV 

V Z<"LEAB:tNG X 
i::i:i Z<-(-A\' ■^•::X)/x 

V 

A<"' ABC BEF' 

LEABING A 
ABC BEF 
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Left-Justify the Names in a IVIatrix: 

V Z<-LJ X 

i::i:i z<"<-*/a\x:::=' ')0x 

V 



NAME:S*-3 6p' sue JAN DAVE " 

NAMES 

W W bl* 

JAN 
DAVE 

LJ NAMES 
SUE 
JAN 
DAVE 

Find the Index of a Name in a Table: 

viNDExcrnv 

V Z4-NAME INDEX TABLE 
CI 3 Z<"((TADLEA.:=:<~ltpTABLE)tNAME))/xltpTABLE 
V 

NAMES 
SUE 
JAN 
DAVE 

'JAN* INDEX NAMES 
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Insert Blank Lines into a Character Matrix: 

?BLANI<LINESi;:OJV 

V z^x blankl:i:ne:s m 

i:: 1 :i n- <(< 1 1 pM )+!..< 1 1 pM ) ->x ) p ( x p i ), o ) \m 

name::b<"6 «+p'don dan sue Jih tgm kxm ' 

NAMES 
DON 
DAN 
SUE 
JIM 

TOM y The left argument determines how 

KIM y^ often the blank lines are inserted. 

2 BLANK LINES NAMES 
DON 
DAN 

SUE 
JIM 

TOM 
KIM 

Print a Matrix Using a Shared Variable: 

ypRiNTi::n:iv 

V PRINT x;z;p 

c:i:3 cR*"0AV[:[jio+:i.563 

1:2.1 P<-*PRT" 

1:3:3 H"l OSVO 'P' 

\:mi p<""i.i, (tX) ,cr 



V 



SUE 
JAN 
DAVE 

SUE 
JAN 
DAVE 



NAMES<"3 i+p'SUE JAN DAVE ' 
NAMES 



PRINT NAMES 
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Drop Leading Blanks or More than One Consecutive Blank from a Character 
String: 

vscan[:d::iv 

S? Z<"SCAN X 

i:;u li-i^iix/' ')v •i?<sj.(i)X)/Xf' •,x 

V 

A<-* ABC D EF" 

SCAN A 
A B C D El- 
Convert a Scalar or Vector to a Matrix: 

vcDNVERTi::o:iv 

? Z^-CONVERT X 

i:::i:i -ko i 2 ===Pf:>x)/(BCALAR, vector, matrix) 

1:2:3 MATRIX :Zf-X 

Z^n SCALAR :Z<" :l 1 pX 

i::5:i -^o 

1:6:1 VECTOR:Z<"<:l. ,pX)pX 

Afl 
pA 

A<-CONVERT A 
pA 

1 1 

Join Two Variables Together Side by Side: 

?BY 1:0:1? 
V Z<-A BY BjROU 

i::i.:i A<-(2t(pA) , 1 DpA 

1:2:1 B<"(2t(pB), :l 1. )pB 
1:3:1 ROWflt(pA)rpB 

!:»i-::i A<-<Roy/":LtpA)tA 
i::5:i b<"(rgu, ■•i.tpB)tB 

1:6:1 Z^-A,B 

? 

A<-2 2p'A' 

B<"3 3p'B' 

A BY B 
AABBB 
AABBB 
BBB 
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Join Two Variables Together One on Top of the Other: 







V0Ni:rj3V 




V 


Z<-A ON BjCOL 


c 1 :i 




A<-("2t 1 1 ,pA)pA 


1:23 




B<"("2t 1 1 ,pB)pB 


i::n 




COL<""'lt(pA)rpB 


i:«+3 




A<-<(1.tpA),C0L)tA 


1:5:1 




B<"((ltpB) ,COL)tB 


\:6'Ji 


V 


z<"A,i::i.:3 b 

A<"2 2p'A' 
Bf-3 3p'B' 
A ON B 


AA 






AA 






BBB 






BBB 






BBB 
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Chapter 10. Input/Output Control 



Input/output operations consist of the following: 

• Reading and writing data records on a tape or diskette data file 

• Reading and writing data on the display screen 

• Printing data records 

In this chapter, the following topics concerning input/output control 
are discussed: 

• Sequential and direct access data files 

• Logical and physical records 

• Types of data file formats 

• APL internal code to EBCDIC (extended binary coded decinnal 
interchange code) translation 

• The 5110 I/O processor 

• Establishing an APL shared variable as the connection between the 
active workspace and the I/O processor 

• Using the APL shared variable for input/output operations 

• Retracting the shared variable offer 
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SEQUENTIAL AND DIRECT ACCESS DATA FILES 

Sequential access data files can be on tape or diskette: however, 
direct access data files can only be on diskette. The data file is 
specified as either a sequential access or direct access data file when 
it is initially created (see Specifying the Operation to be Performed 
later in this chapter). 

All 5110 data files are created sequentially: that is, individual records 
are written to the file in sequential order. 

Data File 



Record 1 



Record 2 



Record 3 



Record 4 



Record 5 



After a data file is created, data can be read from the file as follows: 

• For a sequential access file, the records are read in the same 
sequence as the records were written to the file. For example, the 
first and second record must be read before the third record can be 
read. Also, if you want to read a record previous to the last record 
read, you must start the operation over from the beginning of the 
data file. 

• For a direct access data file, you specify the record(s) that are to be 
read from the data file. For example, you can specify that the fourth 
record in the file be read (without reading the previous three 
records) then after the fourth record is read you can specify that the 
second record in the file be read, and so on. Also, multiple records 
can be read with one statement. 



LOGICAL AND PHYSICAL RECORDS 

A logical record is the individual record written to a data file. For 
sequential access data files, the size of each logical record can vary. 
For example, one logical record might require 10 bytes of storage and 
the next logical record might require 20 bytes of storage. For direct 
access data files, each logical record requires the same amount of 
diskette storage. Generally, each logical record must be the same 
shape and representation as the other logical records in the data file. 

A physical record is a certain amount of tape or diskette storage. For 
tape, a physical record Is 51 2 bytes. For diskette, a physical record is 
the same as the diskette sector size (128, 256, 512, or 1024 bytes). 



108 



TYPES OF DATA FILE FORMATS 

For Sequential Access Data Files 

There are two types of data file formats for sequential access data 
files: 

• APL internal format 

• General exchange format 

Following is a description of these data file formats. 

APL internal Format 

The APL internal format allows data to be written to the data file in 
the same format as that stored in the active workspace. For example, 
the first record written to the data file might be a numeric 10 x 20 
matrix, and the second record written to the data file might be a 
10-element character vector. 

General Exchange Format 

The general exchange data format is the basis of exchange between 
the 5110 APL and BASIC languages. The general exchange format 
only allows character scalars or vectors to be written to the data file. 
Therefore, when the system is storing numeric data in data files with 
the general exchange data format, the format function must first be 
used to change the data to a character scalar or vector. 

The following rules apply to a general exchange format data file that is 
written using the APL language for later processing using the BASIC 
language. 

1. All data items must be separated by commas. For example, the 
numeric vector 13 5 6 must be changed to character data, then 
commas must be placed in the blank positions. The following 
statement replaces blanks with commas in a character vector: 

X C ( X=- ' ' ) / \ pX _h" ' , '_ where X is the character vector. 

2. Negative signs must be replaced by minus signs. 

3. The 5110 BASIC language accepts only the first 255 characters in 
each character constant. 

4. The 5110 BASIC language creates a logical record for each PUT 
statement or each row of an array with a MAT PUT statement. 
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When the 5110 APL language is used to read a general exchange 
format data file (see To Read a Sequential Access Data File later in 
this chapter), the following actions are taken by the 5110 if a cursor 
return character (hex 9C) or end-of-block character (hex FF) was 
embedded in a character vector that was written to the data file: 

© If a cursor return character was embedded in the character vector, 
the data will be read from tape in a different sequence than it was 
written to tape. This condition occurs because as the interchange 
data is written to tape, the system writes an end-of-record 
character (hex 9C) after each character vector (record) that was 
written to tape. The end-of-record character and the cursor return 
character are the same. When used on tape, this character 
separates the data (records) so that it can be read from tape in the 
same sequence as it was written to tape. However, if a cursor 
return character is embedded in the data that was written to tape, 
the system will recognize it as an end-of-record character when the 
data is read from tape. 

« If an end-of-block character was embedded in the character vector, 
any data from the embedded end-of-block character to the next 
physical record is not read from tape. This condition occurs 
because the system looks at the tape in 512-byte segments (one 
physical record). A physical record can be terminated by an 
end-of-block character (hex FF). When the system is reading data 
from the tape and an end-of-block character is encountered, the 
system skips to the next physical record and continues reading data. 
Therefore, if an hex FF character is embedded in the data that was 
written to tape, the system recognizes it as an end-of-block 
character when the data is read from tape and skips ahead to the 
next physical record. 



For Direct Access Data Files 

There are five types of data file formats for direct access data files. 
These formats are: 

• APL internal format 

« General exchange format 

» Unblocked and unspanned format 

» Mixed format 

• Nontranslated format 

F^ollowing is a description of these data file formats. 
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APL internal Format 

The APL internal format allows data to be written to the data file in 
the same format as that stored in the active workspace. However, 
unlike sequential access data files, all the records written to the data 
file must have the same shape and internal representation. For 
example, all of the records written to the data file must be one of the 
following: 

• Character data 

• Numeric binary data (all zeros and ones) 

• Numeric fixed point (all integers in the range -2^^ to 2^'*-^) 

• Numeric floating point (all other values) 

These records must have the same shape and representation because, 
when multiple records are read from a direct access data file, the 
records are laminated (joined) together along a new first dimension 
(see Updating a Direct Access Data File later in this chapter). 

General Exchange Format 

The general exchange format for direct access data files is similar to 
the general exchange format for sequential access data files (see For 
Sequential Access Data Files under Types of Data File Formats in this 
chapter). However, when the general exchange format is used with 
direct access data files, all the records written to the data file must be 
character data and must have the same shape (p DATA) as the first 
record written to the data file. The records must have the same shape 
because, when multiple records are read from a direct access data file, 
the records are laminated together along a new first dimension. 
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Unblocked and Unspanned Format 

The unblocked and unspanned format is the basis for general 
exchange with other products using diskette storage. In this case, the 
file name cannot exceed 8 alphameric characters, and the diskette 
sector size must be 1 28 or 256 bytes. 

The unblocked unspanned format allows only character scalars or 
vectors to be written to the data file, with each record starting on a 
sector boundary. Also, the records cannot exceed (span) a sector 
boundary. 

Sector Boundaries 

1"^ 




The records cannot exceed sector boundaries 



When the unblocked and unspanned format is used, all the records 
written to the data file must have the same shape (p DATA) as the 
first record written to the data file. The records must have the same 
shape because, when multiple records are read from a direct access 
data file, the records are laminated together along a new first 
dimension. 

Since the unblocked unspanned format requires each record to start 
on a sector boundary, to prevent wasted diskette storage the record 
size should be as close as possible to the sector size. The unused 
diskette storage in each sector is unavailable for storing data (see 
Type U Data File in Chapter 8, Diskette Concepts). 
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Mixed Format 



The mixed format, like the APL internal format, allows data to be 
written to the data file in the same format as the data is stored in the 
active workspace. However, the mixed format also allows you to 
write records that have different internal representations on the same 
data file. For example, you can write character data, logical data, 
numeric fixed-point data, and numeric floating-point data on the same 
data file. With the mixed format, the first record written to the data 
file determines how much file storage is allocated for each additional 
record to be written to the data file. For example: 



1st Record 
100 Bytes 



100 Bytes 



100 Bytes 



100 Bytes 



100 Bytes 




If the first record requires 100 bytes of file storage, 100 bytes of 
storage are allocated for each additional record. See Storage 
Requirements in the 51 10 APL Reference Manual for information on 
how many bytes of storage are required for each data type. 

As various size records are written to a mixed format data file, any 
unused diskette storage allocated for each record is unavailable for 
storing data (see Type M Data File in Chapter 8, Diskette Concepts). 

Because the records in a mixed format data file do not have to be the 
same shape or internal representation, only one record at a time can 
be directly accessed from the data file. That is, multiple records 
cannot be laminated together. 
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Nontranslated Format 

The nontranslated format is used primarily for reading diskettes from a 
non-5110 system and the diskette does not have standard 5110 file 
types. Therefore, unless you need to read diskettes that do not have 
standard 5110 file types, you might want to skip this topic. 

The nontranslated format is the only format that is not specified when 
the data file is initially created. The nontranslated format can be 
specified only when the system is reading from or writing to any 
diskette data file that already exists. When data is written to a direct 
access data file using the general exchange or unblocked unspanned 
format, the APL internal code is translated to EBCDIC code before the 
data is written on the diskette. This EBCDIC code is then translated 
back into the APL internal code when the data is read back into the 
active workspace. 





K K . 


APL Internal Code 


y EBCDIC Code 
>i 1 


-f 6 


>i 


^ APL Internal Code 


<^ EBCDIC Code 


N 


1 



Active Workspace 



Translation 
Tables 



Diskette Storage 



However, when the nontranslate format is specified, all attributes of 
the file are ignored and any existing diskette file can be read from or 
written to. In this case, as the data is being read from or written to 
the file, the data is not translated from the EBCDIC or APL internal 
code to the other code. 

Instead, as data is being read in the nontranslate format from an 
EBCDIC diskette file, the EBCDIC representation of the data is placed 
in the active workspace. Or when data is being written in the 
nontranslate format to the diskette file, the APL internal representation 
of the data is written to the diskette file. 
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Note: Assuming DIO is 0, the APL internal representation of a 
character is equivalent to the hexadecinnal value of that character's 
Index in the atomic vector. For example, the APL internal 
representation of the character A (DAV [86]) is hex 56 (the bit value is 
01010110). You can determine the bit value of the atomic vector index 
using the encode (x) function. For example: 



':> ':> 



T B6 



P 1 .1.^ p 1 1 p^ 



"Hexadecimal 56 



The EBCDIC character A has a hexadecimal value of CI or a decimal 
value of 193. In non-translate mode (and DIO^I), when the EBCDIC 
character A is read from a diskette, the character is stored internally 
and displayed as a lowercase h (DAV [193]). 

The nontranslate format allows only character vectors to be written to 
the file. Also, each sector on the diskette is considered one record. 
Therefore, if you specify that three records should be read or written, 
you will read or write three sectors on the file. 



Sector Boundaries 




When nontranslate forniat is used, 
three records are equal to three sectors. 
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THE 5110 I/O PROCESSOR AND SHARED VARIABLES 

The 5110 I/O processor is responsible for transferring data from the 
active workspace to the tape, the diskette, the display screen, or the 
printer, and for transferring data from the tape, the diskette, or the 
display screen to the active workspace. Before individual data records 
can be transferred by the I/O processor, a shared variable must be 
established as the connection between the active workspace and the 
I/O processor. That is, the variable is shared between the active 
workspace and the I/O processor. 

Once this connection is established, the shared variable is used to 
send control information and data to the I/O processor and to receive 
return codes and data from the I/O processor. 



116 



ESTABLISHING AN APL SHARED VARIABLE 

A variable must be offered to the I/O processor before the variable 
can become a shared variable. To do this, you must use the DSVO 
(shared variable offer) system function. The DSVO function requires 
two arguments; the left argument must be 1 (to specify the 5110 I/O 
processor), and the right argument must be character data that 
represents the variable name(s) to be shared. If more than one name 
is required, the names may be entered as a character matrix with each 
row representing an individual name. For example: 

I DSVO 'A' -• —The variable name A is 

offered to be shared. 



1 nSVD 3 Ip'ABC 

The variable names A, B, and C are 
offered to be shared. 

The DSVO function generates an explicit result of 2 for each variable 
name that is successfully established as a shared variable with the I/O 
processor. For example: 



OSVO 3 Ip'ABC* 




There are two users of the shared variable, the 
active workspace and the I/O processor. This is called 
the degree of coupl ing. 

A or 1 is the result of the DSVO function for each variable name that 
is not successfully shared with the I/O processor. If the result is 1, 
the left argument of the DSVO function was a value other than 1. In 
this case, the variable name must be retracted and offered as a shared 
variable again with a 1 as the left argument of the DSVO function 
(retracting the shared variable name is discussed later in this chapter). 
If the result is 0, an error message is also displayed. 

You can establish up to 12 shared variables in the 5110 active 
workspace. If you attempt to establish more than 12 variable names 
as shared variables, the error message INTERFACE QUOTA 
EXHAUSTED is displayed. The statement (OiK^gSVO [JNL 2)/0NL 2 
displays the existing shared variable names in the active workspace. If 
12 shared variable names are already established, you must retract a 
shared variable name before another variable name can be offered. 



Input/Output Control 1 1 7 



USINCa APL SHARED VARIABLES 

Once a shared variable is established as the connection between the 
active workspace and the I/O processor, you can do the following 
input and output operations: 

• Create a new sequential access or direct access data file. 

• Add data to an existing data file. 

• Read data from a sequential access data file. 

• Read-only data from a direct access data file. 

• Update (read and write) data in a direct access data file. 

• Read data from and write data to the display screen, 
o Send data to the printer. 

The first value assigned to the shared variable must be a character 
string (enclosed in single quotes) that specifies the operation to be 
performed. Specifying the operations to be performed and doing 
input/output operations are discussed next. 
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To Create a New Sequential Access or Direct Access Data File 

The first value assigned to the shared variable must specify the 
operation to be performed as follows: 

OUT A 

SV ^ 'OUTF device/file number ID = (file ID) MSG = OFF TYPE = I ' 

Type of data file: ^^ M 

• OUT — Sequential access 

• OUTF - Direct access Type of data file format: 

• A - APL internal 

• I — General exchange 
Direct access f • U - Unblocked/unspanned 
files only 1 • M - Mixed 

For example: 



BV<"'OUTF 11003 ID- (SALES) MSG^:aF"F- TYPE;>==U 

t 



Unblocked and unspanned 
data file format. 



The error messages are not displayed. 
The data file identification is SALES. 



Diskette drive 1, file 3. 
Create a direct access data file. 



(See the /BM 51 JO APL Reference Manual for a detailed description of 
each parameter.) 
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Once the operation to be performed is specified to the I/O processor, 
the I/O processor assigns a return code to the shared variable. For 
example: 

SVf'OUTF 11.0 03 ID- (SALES) MSG-OFF TYPE-U 

SV-* ~~The return code is checked by referencing the 

>^ shared variable. 



"The return code is a two-element vector. 

In the previous example, the return code is 0, which indicates that 
the operation to be performed is successfully specified to the I/O 
processor. See the IBM 5110 APL Reference Manual for a description 
of all the return codes. 

Once the operation to be performed is successfully specified, the 
shared variable used to specify the operation is then used to specify 
data that is to be written on the data file. That is, each time new data 
is assigned to the shared variable, the I/O processor transfers that 
data to a data file and assigns a return code to the shared variable. 
For example: 

^'V<"1 2t ' RECORTi ONE ' Remember, in this example, the 

ey "*" data file format is unblocked and 

« ,j " unspanned. All of the records in the 

SV<-3 ?t ' RECORD TWO * ^^^^ ^''^ "^"^^ ^^^^ **^® ^^"^^ shape. 

SV 



yy ^ — Notice that the shared variable 

XO STATUS: INVALID OPERATION cannot be referenced more than 

I N T F R R U P T o"^^ ^° check the return code. 

SV 

A 

SV<-12t ' RECORD THREE" 

X<"SV 

X 

•The return code can be assigned to another 
variable and then checked more than once. 
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When ail of the data is written to the data fiie, the operation must be 
terminated. The operation can be terminated by assigning an empty 
vector to the shared variable. For example: 



SV 



■ Empty vector 







The operation is terminated. The variable 
SV is still shared with the I/O processor. 
Therefore, SV can be used to specify and 
perform another input/output operation. 

See the IBM 5110 APL Reference Manual for a description of other 
ways to terminate the operation. 



To Add Data to an Existing Data File 

There will be times when you want to add data to an existing data file. 
If you specify an OUT or OUTF operation, the data you write to the 
file always starts at the beginning of the file and the new data is 
written over any existing data. Therefore, to add data to a data file 
starting after the last record in the file, you must specify the operation 
to be performed as follows: 

SV ^ 'ADD [device/file number] [ID = (file ID)] [MSG = OFF] ' 



For example: 







SV<- ' ADD :U.003 :i:Dn::( BALES) iiSG-OFF 
SV 

Do not display the error messages. 
The file identification of the existing data file. 
The data file is on diskette drivel , file 3. 
Add data starting after the last record in the data file. 



Even though the device/file number and ID = (file ID) parameters are 
optional, one or the other of these parameters must always be 
specified. 
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The type of data file (sequential access or direct access) and data file 
format are determined by the attributes of the existing data file. In this 
case, assume this example is continued from the previous topic, the 
file is a direct access, unblocked, and unspanned data file. 

Once operation is specified, data can be sequentially written to the 
data file. For example: 









SV<-12t "RECORD FOUR' 
SV 

SV<"12t "RECORD FIVE' 
SV 



SV<xO 
BV 



You can terminate the operation 
by assigning an empty vector to the 
shared variable. 



To Read a Sequential Access Data File 

Once a sequential access file is created, the records are sequentially 
read from the data file. That is, the records are read from the data file 
in the same sequence as the records were written to the data file. 
You specify the operation to be performed as follows: 

SV-e 'IN [device/file number] [ID = (file ID)] [MSG = OFF]' 
For example: 







S Vf- "IN 110 "I- I D-= ( SEQ ) MBG-OFF ' 
SV 

Do not display the error messages. 
The existing data file identification. 
The data file is on diskette drive 1 , file 4. 
Read data from a sequential access data file. 
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After the operation is specified, the I/O processor assigns a return 
code to the shared variable. The I/O processor then assigns a new 
record from the data file to the shared variable each time the shared 
variable is referenced. For example: First, to create a sequential 
access file with 5 records. 

1 nsvo "sv 

■;:> 

78EQUENTIALi::ri:iV 
? SEQUENTIAL 

i::i::i svf'ouT no on- :i:d====<seq) typf^^^^a* 

l:2::i n-i 

i::3:;i lgqp : -k v/()?<;x<"SV)/error 

i:M::i sv^" record ',^1 

151 ••K5>3>:i;fl)/LOOF 

i:6::i sv^xo 

i::?:^ ■•>(a/o="X<"BV)/o 

\:bi error: -creating the data file failed, the return code is 

t 'f X 



sequential 



Now, to read the 5 records from the data file. 

SV<"' IN ID=:=:(SEQ) ' 

*•* ^ " You should check the return code after the 

" " operation is specified. 

SV- — ———___ 
RECO RD :l '::::r=9- After the return code is checked, each time 



>V ^r-^ the shared variable is referenced, the I/O 
RECORD 2 processor assigns the next record from the 

^^V data file to the shared variable. 

RECORD 3 

X<"SV-« — — If you want to save a record for later use, you 

X must assign the shared variable to another variable. 

RECORD i|- 
SV 
RECORD b ^^^,^ After the last record is read from the file, an empty 

->V ^^^.-^^^^ vector (sO) is assigned to the shared variable. This 

empty vector terminates the operation. (In a 
SV user-defined function, you can check for the 

empty vector. For example: ^ (0 = pX *-SV)/DONE. 

The statement branches to DONE if the last record 
read was an empty vector.) 
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When reading a sequential access data file, the I/O processor does 
not assign return codes to the shared variable. However, if an error 
occurs, an empty vector is assigned to the shared variable and the 
operation is terminated. Then the I/O processor assigns a return code 
to the shared variable that indicates why the error occurred. 

You can also terminate the operation at any time by assigning an 
empty vector to the shared variable. For example: 

GVf' IN ID====(SEQ) ' 


ev 

RECORD :l 

SV 

RECORD 2 

cjiyff. ^ ^ The read operation is terminated. 



SV 




To Update Data in a Direct Access Data File 

Once a direct access data file is created, specified records in the data 
file can be updated. That is, records can be read from the data file, 
updated in the active workspace, and then written back to the data file 
at a specified record location. Unlike the operations discussed so far, 
reading or writing specified records on a direct access data file 
requires a pair of shared variables. One of the shared variables is 
used to specify control information to the I/O processor. The I/O 
processor also assigns the return codes to this shared variable. The 
other shared variable is used for data that is written to or received 
from the data file. The pair of shared variable names must have the 
following characteristics: 

• The shared variable name used to specify the control information 
must have the 3-character prefix CTL. 

• The shared variable name used for the data must have the 
3-character prefix DAT. 

• After the 3-character prefix, the next 15 characters in each name 
must be identical, if specified. For example: 



CTLl 



These variable names can be used as 



^^ ' J ^/^ a pair of shared variables, 

or 

CTL NAME^ 

DAT NAME 
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Once the pair of shared variables is established, you specify the 
operation to be perfornned as follows: 



CTL 



'lOR [device/file number] [ID = (file ID)] [MSG = OFF] [TYPE = Nl 
lORH 



Read or write to a 
direct access data file. 
Seethe IBM 5110 APL 
Reference Manual for 
a description of the 
differences between an 
lOR and lORH operation. 



If this parameter is 
specified, the data is 
not translated (see 
Nontranslated Format) . 
The other formats cannot be 
specified when you are 
reading from or writing to a 
direct access data file, because 
these formats were established 
when the file was created. 



For example: 



X 



CTLf-'lOR 11005 3:i>::< DIRECT) MS(3:"":0FF ' 
CTL \ \ k j 

Do not display the error messages. 

The file identification. 

The data is on diskette drive 1 , file 5. 

Read records from or write records to a direct access data file. 

For a read or write operation to a direct access data file, the second 
element of the return code identifies the number of records in the data file. 
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After the operation is specified, the CTL shared variable is then used 
to specify what records to read or write. To do this, you must assign 
a two- or three-element vector to the CTL shared variable, as follows: 



CTL 



starting record number [number of records] 




specifies a read records operation. 

1 specifies a write records operation. 

2 specifies a search by key operation, 
(search by key is discussed 

later in this section). 



If the third element 
is not specified, one 
record is assumed. 



For example: 



CTL<- p 5 3^ 



-Read three consecutive records, starting with 
the sixth record in the file. 



Note: The record numbering starts with zero. 







Therefore, the first record in the file is record number 0, the second is 
record number 1, and so on. Also, you cannot read from or write to a 
record position that was not originally created using an OUTF or ADD 
operation. 

When the CTL shared variable specifies a read records operation, the 
I/O processor assigns the records read from the data file to the DAT 
shared variable. When the CTL shared variable specifies a write 
records operation, the data currently assigned to the DAT shared 
variable is written to the data file. Therefore, the data must be 
assigned to the DAT shared variable before you specify the write 
operation. In each case, after reading or writing records, the I/O 
processor assigns a return code to the CTL shared variable. 
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When you read multiple records from a direct access data file, the 
records are laminated together along a new first dimension before 
they are assigned to the DAT shared variable. For example, assume 
you read three records (character vectors) from the following data file: 



DATA 
FILE 



ABCEF 



GHIJK 





HAN . . -^ 
DAVE. ^ 
JERRY ^ 



CTLf-O 2 3 
CTL 

DAT 



PDAT 



DAN. 



DAVE. 



JERRY 



■ The shared variable DAT contains 

a 3 X 5 character matrix. 

The new first dimension represents the number of records read. You 
can specify each individual record by indexing the new dimension. 



DAN . . 



JERRY 



DATCin 



DATi::3; 
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When you write multiple records to a direct access data file, the 
records must be joined along a new first dimension before they are 
assigned to the DAT shared variable. For example, assume you want 
to write the following three records (character vectors) to a direct 
access data file: 



AAAAA 
BBBBB 
CCCCC 







DAT<i-3 
DAT 



'5p'AAAAABBBBBCCCCC' 



Individual Records 




CCCCC 
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Following is an example of updating records in a direct access data 
file: 



9 o 



I DSVO 2 'Ip'CTLXDATX'^^ -Establish a pair of 

shared variables. 



VDIRECTCrKIV 
7 i\ I jlJEICX ■ J < X -• "" Create a direct access data file. 

a:i CTLX<"'DUTF llOOtj. ID-(DIRECT) TYPET-I ' 

1:2.1 "KO?<iltXfCTLX) /ERRORS"- — ^^.^ 

f 3 1 I i" 1 CTLA and DATA can be 

\: "-I- 1 L D P : C T L X <•• ' R E C D R D ' , t I "^®^ ^o"" ^"y input/output 

151 -K0p<51tXf-CTLX) /ERROR operation. 

161 ">(S>l<-3:-fl)/L00P 

n 7 :.l C T L X^\{) ■*— — ' "'"^'s operation is terminated; 

C B ."I ••* ( 5^ 1 1 X<-CTLX ) /E R RO R "°^ CTLA can be used for other 

ll'9."l ->0 operations. 

n.O:i ERROR: 'CREATING THE DATA FILE FAILED ' 
tlLl 'THE RETURN CODE IS: ' , tX 

y 

DIRECT 
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The data file now looks like this: 
1 



RECORD 1 



RECORD 2 



RECORDS 



RECORD 4 



RECORDS 



CTLX<-"3:0R llOOM- Ii:i~"=(DIRECT) ' 

CTLX 

5 -. — When you specify the operation to a direct 

access data file, the second element of 
the return code is the number of 
records in the file. 



CTLX<"0 

CTLX 


DATX 
RECORIi 1 




DATX<-' RECORD A^ 

CTLXM 

CTLX 











CTLX<-0 1 
CTLX 



DATX 
RECORD 2 
RECORD 3 

CTLX4-1 3 2 

CTLX 
















Data records can be 

read, 

updated, and 

written back at the same record location. 



RECORD 2 



RECORDS 



RECORD 4 



RECORD 5 



Data records can be moved from 
one record location to another 
record location. 



RECORD A 


RECORD 2 


RECORD 3 


RECORD 2 


RECORD 3 



DATX<-'NEW DATAl 
CTLX<-1 2- 
CTLX 



CTLX<"\0 
CTLX 



New records can replace existing records 
in the data file. 



RECORD A 


RECORD 2 


NEW DATA 


RECORD 2 


RECORDS 



Remember, when you write records to the 
data file, the records must meet the 
requirements of the data file. 



Terminate the operation. Now CTLX and 
DATX can be used for other input/output 
operations. 
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To Search by Key a Direct Access Data File 

When doing update operations to a direct access data file, you can 
search the file for a specific record by first assigning a key value to 
the DAT shared variable and then assigning the following vector to the 
CTL shared variable: 



CTL^ 



starting record number of records 



\ 



Specifies a search 
by key. 



Unlike reading from and writing to 
a direct access data file, the third 
element must be specified for 
a search by key. 



When a search by key is specified, the key value currently assigned to 
DAT is checked against the equivalent number of beginning bytes in 
the specified sectors. The specified sectors include the sector that 
contains the starting record number through the sector that contains 
the last record specified (determined by the number of records 
specified). For example: 

Sector Boundaries 




DAT^" 123M' 
CTL<"2 5 «-l 



The first 4 bytes in three sectors 
are compared with the key value. 



When you are creating a file for search by key operations, the file 
should meet the following requirements: 

• The records are sorted in ascending sequence. 

• The records do not span sector boundaries. However, there can be 
multiple records in a sector. 

• A record that is greater than any key value that might be specified 
should start on the sector boundary following the last valid data 
record. 
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See the IBM 5110 APL Reference Manual for a description of when a 
search by key is connplete. If the search is successful, the record(s) in 
the sector containing the appropriate record is assigned to the DAT 
shared variable (multiple records are laminated together along a new 
first dimension). Also, the second element of the return code assigned 
to the CTL shared variable represents the record number of the first 
record assigned to the DAT shared variable. 



CTL 



"I- 



-The search was successful, and the first record assigned 
to DAT is record number 4. 

To Read-Only Data from a Direct Access Data File 

To read-only data from a direct access data file is the same as reading 
records when updating data in a direct access data file. However, 
when you specify a read-only operation, you cannot write data back to 
the data file (a CTL DOMAIN ERROR is generated); this prevents data 
from accidently being written to the data file. You specify the 
read-only operation as follows: 

CTL ^ 'INR [device/file number] [ID = (file ID)] [MSG = OFF] [TYPE = N] ' 



Read-only data from 
a direct access data file. 
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For example: 



CTL 



;i:nr i:i.oo5 :i:d===:(d:i:rect) hsg^^off 



Do not display the error messages. 

The file identification. 

The data is on diskette drive 1 , file 5. 

Read-only data from a direct access data file. 

The second element of the return code identifies the number of 
records in the data file. 



See To Update a Direct Access Data Fife for a description of how 
records are read from a direct access data file. 



To Read Data from and Write Data to the Display Screen 

Reading and writing data on the display screen is similar to reading 
and writing data on a direct access data file. That is, the operation 
requires a pair of shared variables, with one of the shared variables 
having the prefix CTL and the other having the prefix DAT. You 
specify the operation as follows: 

CTL<-* DISPLAY i::hbg:=:=(:)ff::i ' 



The error messages are not displayed. 
Read or write data on the display screen. 



A pair of shared variables is used for reading and writing 
data to the display screen. 

Once the operation is specified, the CTL shared variable is used to 
specify what character positions to read or write. To do this you must 
assign a two- or three-element vector to the CTL shared variable, as 
follows: 



CTL -f- starting character number [number of characters] 

' \ 

If this element is not 
specified, one character 
is assumed. 




specifies a read data operation. 

1 specifies a write data operation. 
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Note: Each character position on the display screen is considered one 
record. The character positions are numbered as follows: 



LINE 




For example: 



CTL^-0 2 1.0-^ 



■ Read 10 characters starting 
with character position 20. 



When the CTL shared variable specifies that characters be read, the 
cursor appears on the display screen at the character position 
specified by the starting character number. You can then modify the 
information on the display screen for the specified number of 
character positions. Also, the insert, delete, and ATTN key perform 
the same functions within the specified number of character positions 
as they do during standard APL keyboard input. Then, when the 
EXECUTE key is pressed, the specified characters are read from the 
display screen and assigned to the DAT shared variable as a character 
vector. 

When the CTL shared variable specifies that characters be written, the 
data currently assigned to the DAT shared variable is written to the 
specified positions on the display screen. DAT must be a character 
vector with at least as many characters as specified by the CTL shared 
variable. 
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In each case, after reading or writing records on the display screen, 
the I/O processor assigns a return code to the CTL shared variable. 

Following is an example of reading and writing data on the display 
screen: 

1 OSVO 2 7p*CTLIi:r.BPDATD:i:SP" 



ctld:i:s:P<"'d:i:splay' 

CTDCUSP 




DATDXSP 

DISPLAY :i:/o 



CTLDIBPfO 6i|- 6M- 
CTLDXBP 

PDATDISP 



D AID :i: B p<- :i. o 2ii- pD aid :i: b p 



ctld:i:bp<"1 o io2»+ 



The cursor appears on line 14. 





Now, enter DISPLAY 
I/O and press 
EXECUTE. 



After the data is assigned to 
the DAT shared variable, the 
DAT shared variable can be used 
like any other variable. 



Write the value currently assigned 
to DAT on the display screen. 
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The display screen now looks like this: 

DISPLAY :i:/o 

d:i: SPLAY :i:/() 

DISPLAY :i:/o 

DISPLAY :i:/o 

DISPLAY I/O 

DISPLAY I/O 

DISPLAY I/O 

DISPLAY I/O 

DISPLAY I/O 

DISPLAY I/O 

DISPLAY I/O 

DISPLAY I/O 

DISPLAY I/O 

DISPLAY I/O 

DISPLAY I/O 

DISPLAY I/O 

Now, scroll up 2 lines 
and enter 

CTLDISP<-xO 
CTLDISP 


to terminate the operation. 
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To Send Data to the Printer 

You can control what information is printed by using an APL shared 
variable. You specify the operation as follows: 

SV-^ 'PRT [MSG = OFF]' 

The shared variable is used for printing data. 

For example (assume SV is already established as a shared variable): 



8V<-' PRT MSG====OFF" 
SV 







Once the operation is specified, only the information (a character 
scalar or vector) assigned to the shared variable is printed. The I/O 
processor assigns a return code to the shared variable after each print 
operation. For example: 











SV^" ■ ONLY THE DATA ASSIGNED' 
SV 

SV^-"TO THE SHARED VARIABLE IS PRINTED' 
SV 



When using a shared variable for print operations, you can only assign 
character scalars or vectors to the shared variable. However, you can 
also print a matrix as follows: 



12 

56 
78 







i) 



HATRIX<-i|. 2p' ;l.23M-567e' 
MATRIX 




cr<-i:iavi;::l57::i 

sv«-::u, (^matrix ),cr. 

SV ' ' -^ 



SV<"\0 
SV 



Terminate the 
operation. 



Carriage return character (assuming DI0<-1). 



This expression catenates a carriage 
return character at the end of each 
row of the matrix and then ravels 
the matrix into a vector, as follows: 



1 2CR34CR 56CR78 



<- The last 

CR is dropped. 



Now, when the vector is printed, 
a new line is started each time 
the carriage return is encountered, 
as follows: 



1 2 
34 
56 
78 
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TERMrNATING THE OPERATION AND RETRACTING THE SHARED 
VARIABLE OFFER 

As discussed previously, you can terminate an input/output operation 
by assigning an empty vector to the appropriate shared variable. After 
you terminate the operation, the I/O processor assigns a return code 
to the shared variable, and then the shared variable can be used to 
specify another input/output operation. 

See the IBM 5110 APL Reference Manual for more information on 
assigning an empty vector to the shared variable. 

There are four other ways that you can terminate the operation: 

© Use the DSVR system function to retract the shared variable offer. 

• Use the DEX system function to expunge the shared variable name. 

o Complete execution of a user-defined function in which the shared 
variable is made local to that function. 

« Use the )ERASE system command to erase the shared variable 
name. 

In each case, the operation is terminated and the shared variable offer 
is retracted. However, a return code is not assigned to the shared 
variable to indicate whether or not the operation was terminated 
successfully. 

Generally, the DSVR function is used after the operation is terminated 
and the shared variable is no longer required for any input/output 
operations. The DSVR system function requires one argument; this 
argument must be character data that represents the shared variable 
names being retracted. If more than one name is required, the names 
may be entered as a character matrix with each row representing an 
individual name. For example: 

OB V R ' A ' -• The variable name A is no 

longer a shared variable. 



DBVR Z .1.(0 "ABC 



^The variable names A, B, and C are no 
longer shared variables. 



The DSVR function generates an explicit result of 2 for each shared 
variable offer with the I/O processor that is successfully retracted. For 
example: 

X<"OSVR 3 1 9 ' ABC ' -• In this case A, B, and C 

X are shared variables. 

'!> '!> ':> 
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Once the OSVR function is used to retract a shared variable offer, the 
shared variable becomes an ordinary variable. 



Af-3M.|. 
A 



The following chart summarizes the data file types for input/output 
operations. Sequentially accessed data files require one shared 
variable, and directly accessed data files require a pair of shared 
variables (CTL/DAT). Records in the data files can be blocked and 
spanned or unblocked and unspanned. Blocked and spanned records 
can span sector boundaries. Unblocked and unspanned records cannot 
span sector boundaries; that is, the record must be less than or equal 
to the sector size and there is only one record per sector. 



TYPE== 

Parameter and 
Data F=ormat 


File Type 
Displayed Using 
the )LIB Command 


Comments 


Sequential Direct 
(OUT) (OUTF) 


A 

APL internal 

blocked/spanned 


8 10 


• The 51 1 defaults to TYPE=A If the parameter is not 
specified. 

• For file type 10, all the records in the file must be the same 
size and representation (character, binary, fixed point, or 
floating point). 


1 

Character data 

blocked/spanned 


2 9 


• File types 2 and 9 can be read sequentially using an IN 
operation. 

• File type 9 (blocked and spanned) uses less storage than 
file type 10 for character data. 

• For file type 9, all the records in the file must be the same 
size. 


U 

Character data 

unblocked/ 

unspanned 


9 or B9 


• File types 9 and 89 can be read sequentially using an IN 
operation. 

• File type 89 is the basis of exchange with other products. 

• All the records in the file must be the same size. 


M 

APL internal 

blocked/spanned 


8 15 


• For file type 15, all the records in the file must use the 
same or less storage than the first record written to the file, 
and records must be read or written one at a time. 
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SAMPLE INPUT/OUTPUT OPERATIONS 

»w SEQUENTIAL I/O K-n- 

8 e q u (* n i i a I f \ [gs on cl i sk e 1 1 o <^ r t? essentially t h e sa m e 
a *•> t a p e f i I e s . T' h e t w o t y p e «> a v e : 

(3ENERAL EXCHANGE (File type 2) 

A PL INTERNAL (Fi le type 8) 

S e i'A u e n t i a I file s r e q u i r e only o n e <sh a v e d m a v i a t) I e , 
:l. OSVG ' SEQDBK ' 



T h i s e X a mp I e sp e c i f i e s ' GLilf" ' to i n d i c:a t e o u t p u t 
and defaults to the A PL INTERNAL File Type. 

SEQDSK <•■ ■ GUI" 1 1 3. I i:i==:= ( TEST ) ' 

Q n c: e t h e ope r a t i o r^ I s e s t a I:) I i s h e (J a n d c h e c k e d 
for va I id comp I et i on w i th a '0 ' return code , 























SEQDSK 



V e c r ds ma y b e wv i 1 1 e n t o t h e disk e 1 1 e f i I e . 
An in t e g e v r e c o v d i s my- i 1 1 e n f i r s t . 



SEQDSK <"X 10 



Always ch e c:k t h e v e t ur n code o n o u t p u t . 
SEQDSK 



A PI.. I NTE RN AL s e q u e n t i a I file s p e r m i t wr i t i n g o f 

any type of data within the same file. For 

e X a rnp I e , you ca r^ write a f I o a t i n g p o i n t v e c: o v d , 

SEQDSK<-.5+\3.0 
SEQDSK 



a n d a binary r e c: o r d , 

SEQDSK <■• :l.5p() 1 1 :l 1 
SEQDSK 



a n (J a c h a r a c t e r r e c: o r cL 
SEQDSK f- 'This is t h e LAST r e c o r d . ' 
SEQDSK 
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You (::a \) n o w c I o s e t h e f i I e , 
BEQD8l<<"xO 
SEQD8K 

a r^ d r e a d w h a t w a s i.iiv I \ t e n \ o t li e d i s k e t t e . 

N C) r !:• t h a t n I y t h g 1H ( o v B t? y i c e / 1-" i U Nam b ev ) i s 
n (? t? d <? d i i:JF> 0? c: i f y a da t a f' i I fa o r^ t li e d i i:jI< e i t e . 

BEQDSK^-'IN 3:D=:==<TEBT) ' 

CJh (•? <::!< l' l"i e v e t uv n c o d e ■ 

SEQD9K 







a r^ d V tj a d e a c h v e c o r d i ri t l"i t? o v d e v I h a + i l 
uas wr i i ten . 

r" i V *!i. t , t h e i n \ t? g e v v (^ c: o v d , 
SEQDSK 
1 2 3 i-l- 5 6 7 B 9 10 

t h e f I. oat i ri g p o i n 1,- v o) c:: o v d , 
BEQDBK 
l.'D 2.5 3.5 »l- . 5 5.5 6.5 7.5 8.5 9.5 10.5 

t h e b i n a r y v o c: o v d , 
BEQDBK 
1 1 1 1 1 J. 1 1 

a n d , f i n a I I y , i b « c i"i a r a c: t o> v r (^ c: o v d . 
BEQDBK 
T h i s i s l h e L A 8 T v e c: o v d . 

■f l"i <a V 0? ii.i ill n u) b e a n <■* tin p t y v «? c l' o v r e t u r \"i o d , 

U.I h i c: h i n d i c: a i" t? s 1: h e o n d of (J a t a o v a n I / o? v r o v . 

BEQDBK 

(;■; h *• c: l< f V a n e v v o v t: o n d i t i o ri . 

BEQDBK 







A ' ' V <•• t u V n c: o d o i ri d I c: a t o ii> that 1 1 . c- v e 
i s no mor t^ data . 
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G E. N E R A 1... E: X C: l-l A N G E (F\ [g typo 2 ) files a r (? h a n cl I (? cl 
i- h t? s a rn e a s A P I.. :i: N T IJ;: R N A 1... r i I e <Li e x c w p t t i"! a t all <:l a t a 
fn u s i b e i n c: h a v a c: i e v f o v rn a t . If" l"i i s \ y p t; o f f i I e rn a y 
1:) (■» ex c: h a n g e cl u.i i t h t h e B A S :i: (" i... a ri g u a g e . 

Both GENERAL EXCHANGE and API.., INTERNAL format 
fiU?s may be yr it ton to tape in a s i m i I ar f ash i on 
a n d b o I h a v e c: o mi:) a l i b I e w i t h t h e 1 BM 5 1 . 

J: n a cl cli t i n , "I" h e '5 :l. :l. u.i i I I v e a d Ivi 1 f i I e l y p e ':r> :l. 
a 11 d 3 . 



142 







:l. OSVO • CTLDSK " 

:l. DSVG * DATDSK ' 

1" w (J s h a v e cl y ar i a b I e s a r o? o f f e r e cl w h i c: h c: a n b e 
used to 9 e t h e v f o v v m c o v cl i n p u t / o u t p u t . 

CTLDSI<<" ' OUTF :L :l. 1 :n:i==^ ( TEST ) ' 

CTLDBK 

Ass J gn m e n t s i o CTLDSK wr i t e r e c: o r els o n i* o the cl j sk e i* t e 
Th e r e c o r ds rn us t all b e t h e sa m e length and i n t e r n a I 
V e p V e s e n -t a t i o n s i n c: e 't h (•? s e a v e d e f a u I i: T Y P I::! -- A r e c: o v d s 

CTLDBK^-lOOp'A' 

CTLDSI<<":l.00p*B" 

CTLDSK<-100p'C' 

CTLDBI<<":l.00p'D' 

CTLDSKf-lOOp'E" 

CTLDBKMOOp'F' 



CTLDSK <•• 20p'G" 

:r.o BTATUS: invalxd data type 

CTLDSK <• 150<:>'H' 

ID STATUS: :i:nval]:d data type 

CTLDBK<":l.0 0pl 
:i:0 STATUS; INVALID DATA TYPE 

N T E t h a \ t h e a s «h g n n^ e n t rn u ir> t b e c: h a v a c: i' e r a n cl the 

I e n g t h m u s t be 3. s i n c: e l hat j s t v u e w i t h the f i r s t 

v e c r d . T he e v r o v f n e ii> s a g e s w e v e d i s p I a y e d b e c: a u s e 
t h e M S B ~" f F p a r a m e t e r w a s n o t s p e c: i f i e d . 
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6 



100 



CTI.j:i8l<<-\0 
CTLDBK 



Th G u t p u i p c? r a t ion i s no w t o v m i n a i' e d . 

N V fn a n y ^ you w o u I d w a n t t o c h t? c; k v (^ l u v n c: o d c? s 

i- a *:j <i> u V i:> V p v p e V a t i o n . i-" o v e x a rn p l e , :l. t R C!: C) D E 

s h u Id a I w a y lii b o? w i l h v & c o r d i n |:> u i: /' o u. t p u l- 

c: 1" I... n s i< <f •■ ■ 1 R 1 1 o :i. i b === < r i:;; s r > ■ 

Til f i I (* i s n o w b e i n g sp s c: i f i e d f o v i n |:) u t o v o u i: p ii 
p f> V a !• i n s , 

Y (J u c: u I d It a v e u ^> o d I N R I o R 1:" A D N L. Y 

or :i:ORH -•••to READ or URITE. 

1 R a n d 1 R i-l d i f f t-j v i n '5 t o v a g o v e <:i. u i v o ni c n l <•> a r^ d 
P V f r m a n c: & , T li o y a v e t Ii o lij a m e i n f u n c t i o n . 

CTLDBK 

N C) T E t h a \ l h o v o a r c 6 v o c:: o v <:l s aval la b I g ■ 

A I I V G a d s a n (J w v i 1 1? s m u i:> t a d {.i v (? s s o n e o f l h e s g 
aciua I ro cords . 

J a d d r g c o r d lij t o a r o c: o r d 1" / C) f" i I o o r i g i n a I I y 
c r a t G d ii s i n g (3 U T F , y o u m u ii> t s p e c: I f y a n A D D 
p t) r alio n . 

CTLDSK will now be? us(m:I lo read and write and 
JCi A T D 9 1< i s t h g y a r i a b I g c o n t a i n i n g t h o d a t a . 

CTLDBK*.- A B C 

t t t NUMBER OF RECGRDB TO READ OR URITE 

t t ■■" FIRBT RECORD TO READ OR URITE 

t READ OR URITE (READ^^^^O AND yRITE====:l. ) 



CTLDBK <-0 

T" h i i:> s a y s t o r o a d t h g f i r s l r g c o r d < R E C R Ii ) a n d 
r a d n I y o n g r o c:: o r (i ujh i (Lh i s t li o d «;• f a u 1 1 f o r 
l h II u. fn b G r o f r o? c o r d *:i 

PDATDBK 
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DATDBKLJ. 2 3 'I- 51 
AAAAA 

CTLDSKfO :l. 3 

Y u 1-1 a V f r (^ a cl 3 v o? c o v cl s s t a v t i n g w i t h t h e- s e c: o n (J o n t? . 

PDATDBK 
3 :l.()0 

DATDSKi::; 12 3 m::! 

BBBB 
CCCC 
DBDD 

DATD8l<^J.00p"Z' 
CTLDSK^-l :l. 

N w you h a v (^ u^ v i l !: (? ii a n e w «> (■? c: o n cl v t? c o v cl c: o n t a i r^ i n 9 
:i. Z ' S . T c: h & c: k y u c: a n v (^ r e a cl t i-i f i r s t t h v e <■? . 

CTLDSK^" 3 
PDATDSK 
3 :l.0 



AAAA 
ZZZZ 
CCCC 



DATDSKi::;:!. 2 3 'i:! 



CTLD8I<^\0 



T h i s 1 1? V in i \) a l e s t h <•? i n p u t / u i- p 1.1 1 p e v a t i n s . 
CTLDSK 
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USING THE )RESUME COMMAND 

There might be times when you are using a user-defined function to 
do I/O operations and you want to stop the I/O operation until a later 
time. If you suspend the user-defined function by pressing ATTN once 
(a weak interrupt) and then write the contents of the active workspace 
to the media using the )CONTINUE command, you can use the 
)RESUME command to load the stored workspace into the active 
workspace and reestablish the system as it was. That is, the shared 
variables and suspended function are reestablished in the active 
workspace, and, if you enter -> DLC the user-defined function 
continues execution from the point where it was suspended. 

Note: When you use the )RESUI\/IE command, you must make sure 
that the tapes or diskettes are correctly positioned. See the IBM 5110 
APL Reference Manual for a complete description of the )RESUME 
command. 



MORE ABOUT RECORDS AND FILES 

The basic unit of organized data is the record. A record is a collection 
of related data items that are treated as a unit. For example, the 
driver's license most of us carry is a record. A time card is also a 
record. Each record contains items related to the purpose of the 
record. The related items are called fields. The following illustration 
shows a record containing the fields of information that might be 
found on a driver's license: 

License No. Eyes 

Drivers Name Address Date of Birth \ Height \ Sex 

A . \ \ A , \ ,U 



ROBERT JAMES 



13 FORE AVE. ANYTOWN,N.Y. 



9-30-42 



132-5711 



5-9 



BR 



M 
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Each field in the previous record contains information relating to a 
specific driver. The length of the field is the nnaximum number of 
characters that is to be placed in the field. The next illustration shows 
a record containing the fields of information that might be found on a 
time card: 



Name 



Location 



Date Serial No. Shift Start Time 



TOM ROBERTS 



ENDICOTT 



10-10-74 



83215 




8:00 



A group of records make up a file. Just as a filing cabinet contains a 
number of records in some specific sequence, a 5110 data file also 
contains records in some specific sequence. 

The following illustration shows a record containing customer 
information that would be used in making out an invoice: 



Customer 
Number 



Name 



Street 
Address 



City, State 



Billing 
Code 



137250 



JAMES CONSTRUCTION CO. 



X 



13 TOPPER AVE 



TROY, N.Y, 



13 



The file would contain as many records as there are customer 
numbers. A file should be given a unique name so that the file can be 
distinguished from other files. Because the record in the previous 
illustration contains customer master information, the file could be 
named CUSTOMER. MASTER. A file containing master information 
about the products in your inventory could be named ITEM. MASTER. 

Different files can contain different record layouts. For example, the 
following illustration shows a record that has items related to the item 
file: 



Item 
Number 



\ 



Description 



Price 



874164 



WIDGET 



^^-^ 



Qty in 
Stock 



13.95 



0043 
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Organizing a Dislcette File 

An important part of any data processing job is file organization. File 
organization is the arrangement of records in a file. 



Sequential Access Files 

Sequential access files are processed consecutively. For example, an 
employee master file contains information needed for various reports 
concerning each employee, such as payroll checks. Because checks 
are usually processed in order by employee number, records are 
processed in order. The lowest employee number is processed first 
and so on until the last record, the highest employee number, is 
processed. 

Sequential processing means records are processed one after another 
in the order they occur in the file. To process only certain records all 
records must be processed, or at least read up to the last record to be 
processed. 
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Direct Access Files 

Since sequential processing can be time consuming, it would be 
helpful if diskette records were available like books in a library. That 
is, you could go to an index, find the location where the book is 
stored, go to the right shelf, and get the book you want. No one 
would read all the books in the shelves before reading the desired 
book. Likewise, it would be desirable to skip the records not needed 
in a job and process only the desired ones. Because direct access 
files allow specified records to be processed by record number, the 
limitation of sequential processing can be overcome by an index. 

To create and use an index, you could use the following procedure: 

1 . As you create the direct access, you also create a matrix with 
each row representing a key field in the record. For example, the 
first 7 characters in a record are the item number. As you write 
a record to the file, you also add the item number to a matrix of 
item numbers. 

2. Now, when you want to directly access a record by record 
number, you can find the record number by using the following 
user-defined function (assuming DIO-<-0): 

yZ^-LIBT INDEX ITEM 

i: 1 ::i z ^ • ( < i... :i; s r a . =:=: < - :i. t p i... i s j > 1 1 r i;:: m > > / 1 :i. t p i... :i: s t v 

The explicit result of this user-defined function is the row of the 
matrix that contains the specified item number. This explicit 
result also identifies the record number of the specified item 
number in the data file. 

3. Once you find the record number of the specified item number, 
you can directly access and process that record without regard to 
its relation to other records. 
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Ordered and Unordered Records 

The records in a direct access file can be ordered or unordered. An 
ordered file means that the records are arranged in order according to 
some major control field or by frequency of use. An unordered file 
means that the records are not in any particular order. 

With a 5110, it takes less time to specify and read 100 records at one 
time than to specify and read individual records 100 times. Therefore, 
arranging your records in order of frequency of use might save you 
processing time. For example, a wholesale distributor organizes the 
file of inventory items by frequency of use. Thus, the most active 
items are at the beginning of the file. Then, when the file is used to 
write customer orders, most of the records are located in a small area 
of the file and can be processed as multiple records. In this example, 
the total time to process the orders is less than if the records were 
scattered throughout the entire file. 



Maintaining Diskette Files 

Once a file is created, file maintenance is often necessary. File 
maintenance means performing those activities that keep a file current 
for daily processing needs. Some file maintenance activities are: 
adding, deleting, and updating records. Adding means putting a 
record in a file after the file is created. Deleting means identifying a 
record so it will not be processed with other records. Updating means 
adding or changing some data in a record. 



Adding Records 

Records can be added at the end of a file after a file has been 
created. Thus, the file is extended by the added records. 

Sometimes, however, the new records must be merged between the 
records already in the file. This might be necessary to keep the file in 
a particular order when the control fields of the new records are not 
higher in sequence than those already in the file; for example, when 
you are using the file for search by key operations. To put the new 
records in the proper sequence, you must use an APL user-defined 
function to sort the file and create a new file containing the added 
records or use the Diskette Sort feature if installed. See the IBM 5110 
Customer Support Functions Reference Manual, SA21-931 1, for more 
information on the Diskette Sort feature. 
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Tagging Records for Deletion 

When a record becomes inactive, you nnight not want to process it 
with the other records. A record cannot be physically removed from 
the file during regular processing; therefore, it is necessary to identify 
or tag the record so it can be bypassed. One way to tag such a record 
is to put a code, called a delete code, in a particular location in the 
record. When the file is processed, your user-defined function can 
check for the delete code; if the code is present, the record is 
bypassed. 

When several records in a file have been tagged for deletion, you 
should remove them from the file. This will free diskette space. You 
can remove the deleted records by using a user-defined function to 
copy the records to be retained onto another file or write new records 
over the deleted records. 



Updating Records 

When you update records in a file, you can add or change some data 
on the record. For example, in an inventory file you might want to 
add the quantity of items received to the previous quantity on hand. 
The record to be updated is read into storage, changed, and written 
back in its original location. 



Designing a Record 

The applications that use a certain file determine what data is needed 
in a record. You should study these applications and then decide the 
layout of the record. Layout means the arrangement of fields in a 
record. When you design a record, you must consider processing 
requirements of the record and then determine field length, location, 
and name. 

A name and address file is used to illustrate these design 
considerations. Each record in the file contains the following data: 

Field Size (number of characters) 

Customer Number 8 

Name 20 

Street Address 20 

City and State 20 

Record Code 2 

Delete Code 1 

(Other fields) (total) 47 
Total 1 1 6 
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Determining Field Size 

Field size depends on the nature of the data in the field. First, the 
length of the data may vary. In the example, name is 20 characters. 
The length of each customer's name varies, but 20 characters should 
be sufficient for all names. Secondly, all data in a field might be the 
same length. For example, customer number is eight positions, and all 
eight positions are used in each record. 

There are no firm rules for determining field size. The major problem 
involves fields with variable length data. For example, if a name is 
planned as 15 characters, and a new customer has 19 characters in his 
name, a problem arises when you add his record to the file. To avoid 
this problem, try to estimate the largest length of data that will be 
contained in a field. Use this length to determine the field size. 



Providing for a Delete Code 

Remember that records are not automatically deleted. You might want 
to place a delete code in a record, and then when the file is processed 
you must check for the delete code. In the example, if a customer 
becomes inactive, we do not want to process his record. Thus, a 
one-position field is included to provide for a delete code. 

Of course, if you are using an index to find the records in a direct 
access file, you do not need a delete code. Instead, you can remove 
the record key from the index. See Organizing a Diskette File in this 
chapter for information on creating an index. 



Providing Extra Space 

At this stage in planning, it is often wise to allow for data to be added 
to a record. For example, suppose the name and address file was 
created with the fields described, and at a later time each customer's 
zip code is needed. If all positions in the record are used, there is no 
place to add the zip code. Because the record length is not yet 
established, we can allow for such additions to this record. Although it 
is often difficult at the planning stage to imagine what data might be 
added, it is wise to reserve extra space. A minimum of 10% extra 
space is suggested. 
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Documenting Record Layout 

When record layouts are documented, your APL user-defined function 
might be easier to write. A record layout should include the order of 
the fields in the record, the length of each field, and the name of each 
field. The following illustration shows the layout of a customer master 
record: 



Customer 
Number 

f 



Name 



Street Address 



City and State 



1 89 



28 29 



48 49 



68 69 



3f 



Delete 
Code 



Other Fields \ \ Reserved Space 



127 128 



In the previous example, the sum of the fields is 116 positions. 
However, the record size is 128 positions, thus reserving 12 positions 
for data that might be needed at a later time. 



Determining the Number of Records in a File 

When determining the number of records in a file, you should consider 
expansion for a reasonable time into the future (at least six months). 
Then when you create the file, if you place dummy records in the file, 
these dummy records can then be replaced with valid records at a 
later time. Of course, you can also add records to the file using an 
ADD operation. 
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Chapter 1 1 . Debugging and Error Recovery Techniques 



SUSPENDED FUNCTION EXECUTION 

The execution of a user-defined function can be interrupted 
(suspended) in a variety of ways: by an error message, by pressing 
the ATTN key, or by using the stop control vector (SA). In any case, 
the suspended function is still considered active, since its execution 
can be resumed. Whatever the reason for the suspension, when it 
occurs, the statement number of the next statement to be executed is 
displayed. A branch to the statement number that was displayed or a 
branch to DLC(^nLC) causes normal continuation of the function, and 
a branch out (->-0) removes the function. 

When a function is suspended, the 5110 will: 

• Continue to execute system commands except )SAVE, )COPY and 
)PCOPY. 



• 



• 



Resume execution of the function at statement n when ^-n is 
entered. 

Reopen the definition of any function that is not pendent. A 
pendent function is a function that called the suspended function. If 
a function called a function that called a suspended function, it is 
also pendent (see State Indicator). 

• Execute other functions or expressions. 

• Execute the suspended function again. 

Note: The display of output generated by a previous statement might 
have been interrupted when the suspension occurred. This would be 
caused by the delay between execution of the statement and display 
of the output. 
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STATE INDICATOR 

The state indicator identifies which functions are suspended (*) and at 
what point normal execution can be resumed. Entering )SI causes a 
display of the state indicator. Such a display might have the following 
form: 

)s:i: 
H 1:7:3 •»• 
01:2:1 
F 1:3:1 

This display indicates that execution was halted just before statement 
7 of function H, that the current use of function H was invoked in 
statement 2 of function G, and that the use of function G was invoked 
in statement 3 of F. The * appearing to the right of H[7] indicates that 
function H is suspended; the functions G and F are said to be 
pendent. 

During the suspension of one function, another function can be 
executed. Thus, if a further suspension occurred in statement 5 of 
function Q, which was invoked in statement 8 of G, a display of the 
state indicator would be as follows: 





)s:i: 


Q\:5i 


•)t 


Gi:e::i 




Hill 


•« 


or: 2:1 




Fi:3:] 





An SI DAMAGE error indicates that a suspended function has been 
edited or a pendent function has been erased and the normal 
execution of the suspended function can no longer be resumed. When 
an SI DAMAGE error occurs, the state indicator display will include the 
damaged function name and the statement number "1. For example, if 
function Q is edited and the modification causes an SI DAMAGE error, 
the display of the state indicator would be as follows: 





)s:i: 


Qi:-:i.::i 


•)(• 


gi:b:i 




Hi:7"j 


•)(• 


G 1:2:1 




F 1:3:3 





156 



You can clear a suspension by entering a branch with no argument 
(that is, -►). One suspended function is cleared at a time, along with 
any pendent functions for that suspended function. The first branch 
clears the most recently suspended function, as in the following 
example: 



hi::? 
Gi::2 
Fi::3 



)s:i: 



it is a good practice to clear suspended functions, because suspended 
functions use available storage in the active workspace. Repeated use 
of -)■ clears all the suspended functions; as the functions are cleared, 
they are removed (cleared) from the state indicator. When the state 
indicator is completely cleared, the state indicator display is a blank 
line. 

Note: To display the state indicator with local names, enter the )SINL 
command. 



Debugging and Error Recovery Techniques 157 



158 



Appendix A. 5110 Compatibility with Other APL Systems 



The follwing user-defined functions are example functions that can be 
used to check 5110 user-defined functions for compatibility with other 
APL systems: 



i:: :i :i 

i::2::i 

i:3::i 

i;:'i::i 

1:5:1 

1:6:1 

i:?:i 

1:3:1 

L" 9 :i 

1: 1 :i 

i: 1 1 :i 

i::L2j 



y CHECK i::i:i:iv 

V CHECK F ; EA ; RL ; CR; FL ; ED ; OK) ; npy 
fiCHECK FDR POSSIBLE INCGHPATIBILITES IN FiJNCTTON F 
nEA==:: ERROR ARRAY CL==^COLUiiN LEDGEND 

ftRF::=:RGU FLAGS (ERRORS) RL=-RGU LFnOFND 

n 1 i" 1 " 

0PWf:l32 ^ 



E A ^" PORTABLE CF^-OCR F 

'^'••■^- ' I" ' ' :l. ^ < T < CI. t pE A ),;!.) p "• ;|. f \ 1 1 pEA ) , ' T 

RF^-<v/EA)\')'-* 

CF^-RF, • • ,RL, ■ • ,CF 

FL^-' t ■ i::i.+ea:i 

1;: B ^(2 1 y.p c F ) p 2 :!. 3 ^ ( c: F ) j: . 5 :i < •••• p c; I"- ) t !"• I . 

(^A/EB:=:=' ' )/ 1:1:1 ED 



1: 1 :i 

1:2:1 

1:3:1 

m-3 

1:53 

1:6:1 

i:?:] 

lb:! 

i:9:j 

cio: 

1: 1 J. : 

CI 2: 

i:i3: 

LiM-: 



' li- 
ft RE 
f) ' ' 
nCS 

ni 
c<;; 

Zi- 

li- 
z<- 

Zi- 
Za 



GRT 
POR 
TUR 
OCR 
====LE 
Oi-1 
:^"0A 
'^CF 
Zv( 
Zv( 
Zv ( 
Zv( 
Zv( 
Zv( 
Zv< 
Zv( 



ABLEi;:o:iv 

TABLE CF;CS;0IO 

N A LOGICAL HATRIX (ONES AND ZEROS) THE SAME SHA 
F''-~A I INDICATES CHANGES REQUIRED FOR PORTABII 
GAL CHARACTER SET CF::::CHAR MATRIX OF F 

V[:(Ii|4\9) , (25+X5I1) , (B6+\7J. ) , 159, 160, 161] 

<CS 

CF- • • ) 

■ 1 OSVO' WHEREIN CF) 

"OCC UHEREIN CF) 

"OAI ■ UHEREIN CF) 

"OTS' WHEREIN CF) 

'OTT' WHEREIN CF) 

'OUL' WHEREIN CF) 

"ODL" WHEREIN CF) 



•m:: as 

,..ITY 



vwhereinc:o:iv 
V z<-A wherein b;oio 

i:i.J n LOCATION OF VECTOR A IN ARRAY B 

[:2:i oiofo 

131 ^ li- ( ( -ppB ) 1 1 ) ^ A/i: :i iMii ■•• 1 4- pB ) , pA ) p \ pA ) 00 , ( A<i- , A ) <> . -=B 
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VTE8TF-UNCTI0NCI 
TESTF-UNCTIGN 
5 OCC 20 



IV 



i;; 1 :j 

1:2:1 1. OSVG 'A 
V 



CHECK ■TESTFUNCTIDN 

1:0 :j testfunction 
[:i:i 5 OCC 20 

t 
1:2:1 :l. OBVD ' 




These statements might not 
be compatible with another 
APL system. 
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)CONTiNUE command 69 
)COPY command 46 
)DROP command 76, 88 
)ERASE command 138 
)FILEID command 87 
)FNS command 48 
)FREE command 90 
)LOAD command 45 
)MARK command 75, 88 
)OUTSEL command 95 
)PCOPY command 46 
)PROC command 46 
)PROTECT command 73, 87 
)RESUME command 45, 146 
)SAVE command 69 
)SI command 48 
)SINL command 48 
)SYMBOLS command 48 
)VARS command 48 
)VOLID command 73, 85 
)WSiD command 48 
Dec system function 62, 95 
DEX system function 138 
DLC system function 155 
DPP system variable 95 
DSVO system function 1 1 7 
DSVR system function 138 
-)-DLC 155 
T function 95 



access- protect indicator 82 

active workspace 3, 75 

active workspace control 41 

add data to an existing file 121 

ADD operation 79, 121 

adding records 150 

APL 4 

APL commands 5 

APL expressions 5 

APL internal code 114 

APL internal format 109,111 

APL shared variable 95,117 

APL user-defined function 4 

application 5 

arrays 16 

assignment arrow <- 13 

atomic vector 115 

audible alarm 64 



beginning of extent (BOE) 
BOE 84 
bytes 75 
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catenation 25 

arrays of unequal sizes 26 

matrices 25 

scalers to arrays 26 

vectors or scalars 25 

vectors to arrays 26 
center character string in matrix row 35 
changing workspace environment 43 
character constants 1 5 
character position 134 
clear suspended functions 1 57 
CLEAR WS environment 42 
complex name 87 
compress data 79 
console control 65, 97, 101 
console storage 59 
CONTINUE 69 
controlling display screen 63 
controlling files 72 
convert to a matrix 105 
COPY 46 

count unique characters in vector 35 
create a data file 119 
create a matrix from a vector 31 
creating lists 27 
CTL DOMAIN ERROR 132 
CTL shared variable 1 24 
cursor return character 110 



DAT shared variable 1 24 
data 1 

data cartridge 75 
data file 

create 1 1 9 

direct access 108 

formats 109 

sequential access 108 
data files 75 
data processing 2 
data representation 14 
data security 73 
data types 50 

data written to the data file 120 
debugging 1 55 
degree of coupling 1 1 7 
delete code 1 51 

delete comment lines from a function 
delete duplicate elements 33 
delete function names 34 
delete leading blanks 38 
delete name from list 39 
deleted records 151 
deleting records 150 
designing a record 151 
determining field size 152 
determining size of file 68 
direct access data file 108, 119 
diskette 3, 6, 81 
diskette addressing 83 
diskette drive 81 
diskette files 

organizing 148 

maintenance 1 50 
diskette formats 85 
diskette initialization 81, 86 
diskette sort feature 1 50 
diskette storage 54 
diskette volume ID 82 
display screen 4, 7, 63 

read from 133 

write to 1 33 
documenting record layout 153 
DROP 76, 88 
drop blanks 102 
drop blanks and periods 102 
drop extra blanks 105 
drop leading blanks 102 
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EBCDIC code 114 

empty arrays 21 

end of block character 110 

end of data (EOD) 84 

end of extent (EOE) 84 

EOD 34, 84 

EOE 84, 102 

ERASE 138 

error recovery 1 55 

establishing an APL shared variable 117 



hard copy output 4 

helpful functions 102 
convert to a matrix 105 
drop blanks 102 
drop blanks and period 102 
drop extra blanks 105 
drop leading blanks 102 
find index of name 103 
insert blank lines 104 
join two variables 106 
left-justify 103 
print a matrix 104 
replace periods 102 



fields 146 
file headers 75 
file ID 87 
file maintenance 

adding records 150 

deleting records 151 

updating records 151 
file organization 146 
FILEID 87 

find first nonblank character 33 
find index of name 103 
find location of name in list 39 
FNS 48 
format 6 
format 

APL internal 109, 111 

function 95 

general exchange 109,111 

mixed 113 

nontranslated 114 

unblocked and unspanned 112 
formatting reports 98, 101 
formatting tape 75 
FREE 90 



I/O processor 116 

IN operation 122 

index cylinder 84 

index file 149 

index track 90 

indexing arrays 22 

initialization, diskette 81, 86 

input 2 

input/output operations 118 

INR operation 132 

insert blank lines 104 

interface 1 2 

INTERFACE QUOTA EXHAUSTED 

internal precision 96 

internal storage 3 

lOR operation 125 

lORH operation 125 
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general exchange format 109, 111 
generate a matrix 18 
generating arrays 17 
getting information from a file 71 



join two variables 106 
join vectors and print results 
joining arrays 25 
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key value 
keyboard 
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laminated records 127 

lamination 28 

language elements 13 

left justify 103 

left-justify character string in matrix 36 

library control 67 

list each function in workspace 36 

list each variable in workspace 37 

LOAD 45 

logical data 15 

logical record 108 

lowercase characters 60 



maintaining diskette files 1 50 

make scalar or vector into a matrix 

MARK 75, 88 

MAT PUT statement 109 

matrices 1 6 

merge two variables 33 

mixed format 113 



34 



negative sign 14 
nontranslated format 114 
number of records 1 26 
number of records in the file 
numbers 14 
numeric precision 14 
numeric value range 14 
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operations 

ADD 79, 121 

INR 132 

lOR 125 

lORH 125 

OUT 78 

OUTF 119 

PRT 137 
operations to be performed 
ordered file 150 
ordered records 150 
organizing a diskette file 
OUT operation 78, 119 
OUTF operation 1 19 
output 2 
output format 95 
OUTSEL 95 
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148 



pair of shared variables 1 24 

PCOPY 46 

pendent function 1 55 

perform operation on conditions 

physical record 108 

precision 

internal 96 

printed 96 
print data 137 
printer 3 
printing data 95 
PROC 46 
procedure file 46 
process 2, 8 
program 1, 12 
PROTECT 73, 87 
providing extra space 152 
PRT operation 137 
PUT statement 109 



40 



quotes 15 
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random access 77 

rank of an array 1 9 

read a data file 1 22 

read direct 108, 119 

read from the display screen 133 

read multiple records 127 

read records 126 

read sequentially 122 

read /write head 82 

read-only a data file 132 

record 1 46 

records 

laminated 1 27 

ordered 1 50 

unordered 1 50 

updating 1 24 

designing 151 

fields 146 

layout 151 

logical 108 

numbering 126 

physcial 108 
remove alpha characters from vector 32 
remove duplicate blanks from a vector 31 
replace periods 102 
replace trailing blanks 32 
report formatting 98, 101 
reshape function 17 
RESUME 45, 146 
resume execution 155 
retracting the shared variable 138 
return code 120, 123 
return even numbered elements 32 
right-justify character string in matrix 35 



SA 155 

SAFE switch 73 

sample input/output operations 140 

SAVE 69 

scalars 16 

scaled representation 14 

scientific notation 14 

search by key 126, 131 

search file for a specific record 131 

sector 84 

security 73 

sequential access 77 

sequential access data file 108, 119 

sequentially read 122 



shape of array 17 

shared variable 95,117 

shared variable offer 117 

shared variable pair 124 

SI 48 

SI DAMAGE 156 

simple name 87 

SINL 48 

sort columns of matrix 39 

sort feature 150 

specifying the operation to be performed 118 

starting character number 134 

starting record number 126 

state indicator 156 

stop control 1 55 

storage considerations 49 

storage diskette 54 

storage, internal 3 

suspend I/O operations 146 

suspended functions 155 

symbol table 43 

SYMBOLS 48 

system 3 

system commands 

)CONTINUE 69 

)COPY 46 

)DROP 76,88 

) ERASE 138 

)FILEID 87 

)FNS 48 

)FREE 90 

)LOAD 45 

)MARK 75, 88 

)OUTSEL 95 

)PCOPY 46 

)PROC 46 

) PROTECT 73, 87 

)RESUME 45, 146 

)SAVE 69 

)SI 48 

)SINL 48 

)SYMBOLS 48 

)VARS 48 

)VOLID 73 

)VOLID 85 

)WSID 48 
system functions 

Dec 62, 95, 97 

DEX 138 

DSVO 117 

DSVR 138 
system variable DPP 95 
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tape 3, 6 

tape storage 75 

terminate the operation 121, 138 

track 83 



unblocked and unspanned format 112 

unordered file 150 

unordered records 150 

update a data file 1 24 

updating records 124, 150 

useful statements and functions 31, 102 

user-defined functions 3 



variable name 13 
variables 13 
VARS 48 
vectors 1 6 
VOLID 73, 85 
volume ID 54 



weak interrupt 146 

workspace environment 43 

workspace files 75 

workspace ID 44 

workspace required for I/O operation 53 

write data 120 

write multiple records 127 

write records 126 

write to the display screen 133 

write- protect indicator 82 

writing data to a file 69 

WSID 48 



5110 data files 108 
5110 I/O processor 116 
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